submodule/skia/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 "include/core/SkColor.h"
  12 #include "include/core/SkImageInfo.h"
  13 #include "include/core/SkMatrix.h"
  14 #include "include/core/SkPixmap.h"
  15 #include "include/core/SkPoint.h"
  16 #include "include/core/SkRefCnt.h"
  17 #include "include/core/SkShader.h"
  18 #include "include/core/SkTileMode.h"
  19
  20 class SkBitmap;
  21 class SkColorSpace;
  22 struct SkMask;
  23 class SkMipmap;
  24 struct SkIRect;
  25 struct SkRect;
  26 class SkPaint;
  27 class SkPixelRef;
  28 class SkShader;
  29
  30 /** \class SkBitmap
  31     SkBitmap describes a two-dimensional raster pixel array. SkBitmap is built on
  32     SkImageInfo, containing integer width and height, SkColorType and SkAlphaType
  33     describing the pixel format, and SkColorSpace describing the range of colors.
  34     SkBitmap points to SkPixelRef, which describes the physical array of pixels.
  35     SkImageInfo bounds may be located anywhere fully inside SkPixelRef bounds.
  36
  37     SkBitmap can be drawn using SkCanvas. SkBitmap can be a drawing destination for SkCanvas
  38     draw member functions. SkBitmap flexibility as a pixel container limits some
  39     optimizations available to the target platform.
  40
  41     If pixel array is primarily read-only, use SkImage for better performance.
  42     If pixel array is primarily written to, use SkSurface for better performance.
  43
  44     Declaring SkBitmap const prevents altering SkImageInfo: the SkBitmap height, width,
  45     and so on cannot change. It does not affect SkPixelRef: a caller may write its
  46     pixels. Declaring SkBitmap const affects SkBitmap configuration, not its contents.
  47
  48     SkBitmap is not thread safe. Each thread must have its own copy of SkBitmap fields,
  49     although threads may share the underlying pixel array.
  50 */
  51 class SK_API SkBitmap {
  52 public:
  53     class SK_API Allocator;
  54
  55     /** Creates an empty SkBitmap without pixels, with kUnknown_SkColorType,
  56         kUnknown_SkAlphaType, and with a width and height of zero. SkPixelRef origin is
  57         set to (0, 0).
  58
  59         Use setInfo() to associate SkColorType, SkAlphaType, width, and height
  60         after SkBitmap has been created.
  61
  62         @return  empty SkBitmap
  63
  64         example: https://fiddle.skia.org/c/@Bitmap_empty_constructor
  65     */
  66     SkBitmap();
  67
  68     /** Copies settings from src to returned SkBitmap. Shares pixels if src has pixels
  69         allocated, so both bitmaps reference the same pixels.
  70
  71         @param src  SkBitmap to copy SkImageInfo, and share SkPixelRef
  72         @return     copy of src
  73
  74         example: https://fiddle.skia.org/c/@Bitmap_copy_const_SkBitmap
  75     */
  76     SkBitmap(const SkBitmap& src);
  77
  78     /** Copies settings from src to returned SkBitmap. Moves ownership of src pixels to
  79         SkBitmap.
  80
  81         @param src  SkBitmap to copy SkImageInfo, and reassign SkPixelRef
  82         @return     copy of src
  83
  84         example: https://fiddle.skia.org/c/@Bitmap_move_SkBitmap
  85     */
  86     SkBitmap(SkBitmap&& src);
  87
  88     /** Decrements SkPixelRef reference count, if SkPixelRef is not nullptr.
  89     */
  90     ~SkBitmap();
  91
  92     /** Copies settings from src to returned SkBitmap. Shares pixels if src has pixels
  93         allocated, so both bitmaps reference the same pixels.
  94
  95         @param src  SkBitmap to copy SkImageInfo, and share SkPixelRef
  96         @return     copy of src
  97
  98         example: https://fiddle.skia.org/c/@Bitmap_copy_operator
  99     */
 100     SkBitmap& operator=(const SkBitmap& src);
 101
 102     /** Copies settings from src to returned SkBitmap. Moves ownership of src pixels to
 103         SkBitmap.
 104
 105         @param src  SkBitmap to copy SkImageInfo, and reassign SkPixelRef
 106         @return     copy of src
 107
 108         example: https://fiddle.skia.org/c/@Bitmap_move_operator
 109     */
 110     SkBitmap& operator=(SkBitmap&& src);
 111
 112     /** Swaps the fields of the two bitmaps.
 113
 114         @param other  SkBitmap exchanged with original
 115
 116         example: https://fiddle.skia.org/c/@Bitmap_swap
 117     */
 118     void swap(SkBitmap& other);
 119
 120     /** Returns a constant reference to the SkPixmap holding the SkBitmap pixel
 121         address, row bytes, and SkImageInfo.
 122
 123         @return  reference to SkPixmap describing this SkBitmap
 124     */
 125     const SkPixmap& pixmap() const { return fPixmap; }
 126
 127     /** Returns width, height, SkAlphaType, SkColorType, and SkColorSpace.
 128
 129         @return  reference to SkImageInfo
 130     */
 131     const SkImageInfo& info() const { return fPixmap.info(); }
 132
 133     /** Returns pixel count in each row. Should be equal or less than
 134         rowBytes() / info().bytesPerPixel().
 135
 136         May be less than pixelRef().width(). Will not exceed pixelRef().width() less
 137         pixelRefOrigin().fX.
 138
 139         @return  pixel width in SkImageInfo
 140     */
 141     int width() const { return fPixmap.width(); }
 142
 143     /** Returns pixel row count.
 144
 145         Maybe be less than pixelRef().height(). Will not exceed pixelRef().height() less
 146         pixelRefOrigin().fY.
 147
 148         @return  pixel height in SkImageInfo
 149     */
 150     int height() const { return fPixmap.height(); }
 151
 152     SkColorType colorType() const { return fPixmap.colorType(); }
 153
 154     SkAlphaType alphaType() const { return fPixmap.alphaType(); }
 155
 156     /** Returns SkColorSpace, the range of colors, associated with SkImageInfo. The
 157         reference count of SkColorSpace is unchanged. The returned SkColorSpace is
 158         immutable.
 159
 160         @return  SkColorSpace in SkImageInfo, or nullptr
 161     */
 162     SkColorSpace* colorSpace() const;
 163
 164     /** Returns smart pointer to SkColorSpace, the range of colors, associated with
 165         SkImageInfo. The smart pointer tracks the number of objects sharing this
 166         SkColorSpace reference so the memory is released when the owners destruct.
 167
 168         The returned SkColorSpace is immutable.
 169
 170         @return  SkColorSpace in SkImageInfo wrapped in a smart pointer
 171     */
 172     sk_sp<SkColorSpace> refColorSpace() const;
 173
 174     /** Returns number of bytes per pixel required by SkColorType.
 175         Returns zero if colorType( is kUnknown_SkColorType.
 176
 177         @return  bytes in pixel
 178     */
 179     int bytesPerPixel() const { return fPixmap.info().bytesPerPixel(); }
 180
 181     /** Returns number of pixels that fit on row. Should be greater than or equal to
 182         width().
 183
 184         @return  maximum pixels per row
 185     */
 186     int rowBytesAsPixels() const { return fPixmap.rowBytesAsPixels(); }
 187
 188     /** Returns bit shift converting row bytes to row pixels.
 189         Returns zero for kUnknown_SkColorType.
 190
 191         @return  one of: 0, 1, 2, 3; left shift to convert pixels to bytes
 192     */
 193     int shiftPerPixel() const { return fPixmap.shiftPerPixel(); }
 194
 195     /** Returns true if either width() or height() are zero.
 196
 197         Does not check if SkPixelRef is nullptr; call drawsNothing() to check width(),
 198         height(), and SkPixelRef.
 199
 200         @return  true if dimensions do not enclose area
 201     */
 202     bool empty() const { return fPixmap.info().isEmpty(); }
 203
 204     /** Returns true if SkPixelRef is nullptr.
 205
 206         Does not check if width() or height() are zero; call drawsNothing() to check
 207         width(), height(), and SkPixelRef.
 208
 209         @return  true if no SkPixelRef is associated
 210     */
 211     bool isNull() const { return nullptr == fPixelRef; }
 212
 213     /** Returns true if width() or height() are zero, or if SkPixelRef is nullptr.
 214         If true, SkBitmap has no effect when drawn or drawn into.
 215
 216         @return  true if drawing has no effect
 217     */
 218     bool drawsNothing() const {
 219         return this->empty() || this->isNull();
 220     }
 221
 222     /** Returns row bytes, the interval from one pixel row to the next. Row bytes
 223         is at least as large as: width() * info().bytesPerPixel().
 224
 225         Returns zero if colorType() is kUnknown_SkColorType, or if row bytes supplied to
 226         setInfo() is not large enough to hold a row of pixels.
 227
 228         @return  byte length of pixel row
 229     */
 230     size_t rowBytes() const { return fPixmap.rowBytes(); }
 231
 232     /** Sets SkAlphaType, if alphaType is compatible with SkColorType.
 233         Returns true unless alphaType is kUnknown_SkAlphaType and current SkAlphaType
 234         is not kUnknown_SkAlphaType.
 235
 236         Returns true if SkColorType is kUnknown_SkColorType. alphaType is ignored, and
 237         SkAlphaType remains kUnknown_SkAlphaType.
 238
 239         Returns true if SkColorType is kRGB_565_SkColorType or kGray_8_SkColorType.
 240         alphaType is ignored, and SkAlphaType remains kOpaque_SkAlphaType.
 241
 242         If SkColorType is kARGB_4444_SkColorType, kRGBA_8888_SkColorType,
 243         kBGRA_8888_SkColorType, or kRGBA_F16_SkColorType: returns true unless
 244         alphaType is kUnknown_SkAlphaType and SkAlphaType is not kUnknown_SkAlphaType.
 245         If SkAlphaType is kUnknown_SkAlphaType, alphaType is ignored.
 246
 247         If SkColorType is kAlpha_8_SkColorType, returns true unless
 248         alphaType is kUnknown_SkAlphaType and SkAlphaType is not kUnknown_SkAlphaType.
 249         If SkAlphaType is kUnknown_SkAlphaType, alphaType is ignored. If alphaType is
 250         kUnpremul_SkAlphaType, it is treated as kPremul_SkAlphaType.
 251
 252         This changes SkAlphaType in SkPixelRef; all bitmaps sharing SkPixelRef
 253         are affected.
 254
 255         @return           true if SkAlphaType is set
 256
 257         example: https://fiddle.skia.org/c/@Bitmap_setAlphaType
 258     */
 259     bool setAlphaType(SkAlphaType alphaType);
 260
 261     /** Returns pixel address, the base address corresponding to the pixel origin.
 262
 263         @return  pixel address
 264     */
 265     void* getPixels() const { return fPixmap.writable_addr(); }
 266
 267     /** Returns minimum memory required for pixel storage.
 268         Does not include unused memory on last row when rowBytesAsPixels() exceeds width().
 269         Returns SIZE_MAX if result does not fit in size_t.
 270         Returns zero if height() or width() is 0.
 271         Returns height() times rowBytes() if colorType() is kUnknown_SkColorType.
 272
 273         @return  size in bytes of image buffer
 274     */
 275     size_t computeByteSize() const { return fPixmap.computeByteSize(); }
 276
 277     /** Returns true if pixels can not change.
 278
 279         Most immutable SkBitmap checks trigger an assert only on debug builds.
 280
 281         @return  true if pixels are immutable
 282
 283         example: https://fiddle.skia.org/c/@Bitmap_isImmutable
 284     */
 285     bool isImmutable() const;
 286
 287     /** Sets internal flag to mark SkBitmap as immutable. Once set, pixels can not change.
 288         Any other bitmap sharing the same SkPixelRef are also marked as immutable.
 289         Once SkPixelRef is marked immutable, the setting cannot be cleared.
 290
 291         Writing to immutable SkBitmap pixels triggers an assert on debug builds.
 292
 293         example: https://fiddle.skia.org/c/@Bitmap_setImmutable
 294     */
 295     void setImmutable();
 296
 297     /** Returns true if SkAlphaType is set to hint that all pixels are opaque; their
 298         alpha value is implicitly or explicitly 1.0. If true, and all pixels are
 299         not opaque, Skia may draw incorrectly.
 300
 301         Does not check if SkColorType allows alpha, or if any pixel value has
 302         transparency.
 303
 304         @return  true if SkImageInfo SkAlphaType is kOpaque_SkAlphaType
 305     */
 306     bool isOpaque() const {
 307         return SkAlphaTypeIsOpaque(this->alphaType());
 308     }
 309
 310     /** Resets to its initial state; all fields are set to zero, as if SkBitmap had
 311         been initialized by SkBitmap().
 312
 313         Sets width, height, row bytes to zero; pixel address to nullptr; SkColorType to
 314         kUnknown_SkColorType; and SkAlphaType to kUnknown_SkAlphaType.
 315
 316         If SkPixelRef is allocated, its reference count is decreased by one, releasing
 317         its memory if SkBitmap is the sole owner.
 318
 319         example: https://fiddle.skia.org/c/@Bitmap_reset
 320     */
 321     void reset();
 322
 323     /** Returns true if all pixels are opaque. SkColorType determines how pixels
 324         are encoded, and whether pixel describes alpha. Returns true for SkColorType
 325         without alpha in each pixel; for other SkColorType, returns true if all
 326         pixels have alpha values equivalent to 1.0 or greater.
 327
 328         For SkColorType kRGB_565_SkColorType or kGray_8_SkColorType: always
 329         returns true. For SkColorType kAlpha_8_SkColorType, kBGRA_8888_SkColorType,
 330         kRGBA_8888_SkColorType: returns true if all pixel alpha values are 255.
 331         For SkColorType kARGB_4444_SkColorType: returns true if all pixel alpha values are 15.
 332         For kRGBA_F16_SkColorType: returns true if all pixel alpha values are 1.0 or
 333         greater.
 334
 335         Returns false for kUnknown_SkColorType.
 336
 337         @param bm  SkBitmap to check
 338         @return    true if all pixels have opaque values or SkColorType is opaque
 339     */
 340     static bool ComputeIsOpaque(const SkBitmap& bm) {
 341         return bm.pixmap().computeIsOpaque();
 342     }
 343
 344     /** Returns SkRect { 0, 0, width(), height() }.
 345
 346         @param bounds  container for floating point rectangle
 347
 348         example: https://fiddle.skia.org/c/@Bitmap_getBounds
 349     */
 350     void getBounds(SkRect* bounds) const;
 351
 352     /** Returns SkIRect { 0, 0, width(), height() }.
 353
 354         @param bounds  container for integral rectangle
 355
 356         example: https://fiddle.skia.org/c/@Bitmap_getBounds_2
 357     */
 358     void getBounds(SkIRect* bounds) const;
 359
 360     /** Returns SkIRect { 0, 0, width(), height() }.
 361
 362         @return  integral rectangle from origin to width() and height()
 363     */
 364     SkIRect bounds() const { return fPixmap.info().bounds(); }
 365
 366     /** Returns SkISize { width(), height() }.
 367
 368         @return  integral size of width() and height()
 369     */
 370     SkISize dimensions() const { return fPixmap.info().dimensions(); }
 371
 372     /** Returns the bounds of this bitmap, offset by its SkPixelRef origin.
 373
 374         @return  bounds within SkPixelRef bounds
 375     */
 376     SkIRect getSubset() const {
 377         SkIPoint origin = this->pixelRefOrigin();
 378         return SkIRect::MakeXYWH(origin.x(), origin.y(), this->width(), this->height());
 379     }
 380
 381     /** Sets width, height, SkAlphaType, SkColorType, SkColorSpace, and optional
 382         rowBytes. Frees pixels, and returns true if successful.
 383
 384         imageInfo.alphaType() may be altered to a value permitted by imageInfo.colorSpace().
 385         If imageInfo.colorType() is kUnknown_SkColorType, imageInfo.alphaType() is
 386         set to kUnknown_SkAlphaType.
 387         If imageInfo.colorType() is kAlpha_8_SkColorType and imageInfo.alphaType() is
 388         kUnpremul_SkAlphaType, imageInfo.alphaType() is replaced by kPremul_SkAlphaType.
 389         If imageInfo.colorType() is kRGB_565_SkColorType or kGray_8_SkColorType,
 390         imageInfo.alphaType() is set to kOpaque_SkAlphaType.
 391         If imageInfo.colorType() is kARGB_4444_SkColorType, kRGBA_8888_SkColorType,
 392         kBGRA_8888_SkColorType, or kRGBA_F16_SkColorType: imageInfo.alphaType() remains
 393         unchanged.
 394
 395         rowBytes must equal or exceed imageInfo.minRowBytes(). If imageInfo.colorSpace() is
 396         kUnknown_SkColorType, rowBytes is ignored and treated as zero; for all other
 397         SkColorSpace values, rowBytes of zero is treated as imageInfo.minRowBytes().
 398
 399         Calls reset() and returns false if:
 400         - rowBytes exceeds 31 bits
 401         - imageInfo.width() is negative
 402         - imageInfo.height() is negative
 403         - rowBytes is positive and less than imageInfo.width() times imageInfo.bytesPerPixel()
 404
 405         @param imageInfo  contains width, height, SkAlphaType, SkColorType, SkColorSpace
 406         @param rowBytes   imageInfo.minRowBytes() or larger; or zero
 407         @return           true if SkImageInfo set successfully
 408
 409         example: https://fiddle.skia.org/c/@Bitmap_setInfo
 410     */
 411     bool setInfo(const SkImageInfo& imageInfo, size_t rowBytes = 0);
 412
 413     /** \enum SkBitmap::AllocFlags
 414         AllocFlags is obsolete.  We always zero pixel memory when allocated.
 415     */
 416     enum AllocFlags {
 417         kZeroPixels_AllocFlag = 1 << 0, //!< zero pixel memory.  No effect.  This is the default.
 418     };
 419
 420     /** Sets SkImageInfo to info following the rules in setInfo() and allocates pixel
 421         memory. Memory is zeroed.
 422
 423         Returns false and calls reset() if SkImageInfo could not be set, or memory could
 424         not be allocated, or memory could not optionally be zeroed.
 425
 426         On most platforms, allocating pixel memory may succeed even though there is
 427         not sufficient memory to hold pixels; allocation does not take place
 428         until the pixels are written to. The actual behavior depends on the platform
 429         implementation of calloc().
 430
 431         @param info   contains width, height, SkAlphaType, SkColorType, SkColorSpace
 432         @param flags  kZeroPixels_AllocFlag, or zero
 433         @return       true if pixels allocation is successful
 434     */
 435     bool SK_WARN_UNUSED_RESULT tryAllocPixelsFlags(const SkImageInfo& info, uint32_t flags);
 436
 437     /** Sets SkImageInfo to info following the rules in setInfo() and allocates pixel
 438         memory. Memory is zeroed.
 439
 440         Aborts execution if SkImageInfo could not be set, or memory could
 441         not be allocated, or memory could not optionally
 442         be zeroed. Abort steps may be provided by the user at compile time by defining
 443         SK_ABORT.
 444
 445         On most platforms, allocating pixel memory may succeed even though there is
 446         not sufficient memory to hold pixels; allocation does not take place
 447         until the pixels are written to. The actual behavior depends on the platform
 448         implementation of calloc().
 449
 450         @param info   contains width, height, SkAlphaType, SkColorType, SkColorSpace
 451         @param flags  kZeroPixels_AllocFlag, or zero
 452
 453         example: https://fiddle.skia.org/c/@Bitmap_allocPixelsFlags
 454     */
 455     void allocPixelsFlags(const SkImageInfo& info, uint32_t flags);
 456
 457     /** Sets SkImageInfo to info following the rules in setInfo() and allocates pixel
 458         memory. rowBytes must equal or exceed info.width() times info.bytesPerPixel(),
 459         or equal zero. Pass in zero for rowBytes to compute the minimum valid value.
 460
 461         Returns false and calls reset() if SkImageInfo could not be set, or memory could
 462         not be allocated.
 463
 464         On most platforms, allocating pixel memory may succeed even though there is
 465         not sufficient memory to hold pixels; allocation does not take place
 466         until the pixels are written to. The actual behavior depends on the platform
 467         implementation of malloc().
 468
 469         @param info      contains width, height, SkAlphaType, SkColorType, SkColorSpace
 470         @param rowBytes  size of pixel row or larger; may be zero
 471         @return          true if pixel storage is allocated
 472     */
 473     bool SK_WARN_UNUSED_RESULT tryAllocPixels(const SkImageInfo& info, size_t rowBytes);
 474
 475     /** Sets SkImageInfo to info following the rules in setInfo() and allocates pixel
 476         memory. rowBytes must equal or exceed info.width() times info.bytesPerPixel(),
 477         or equal zero. Pass in zero for rowBytes to compute the minimum valid value.
 478
 479         Aborts execution if SkImageInfo could not be set, or memory could
 480         not be allocated. Abort steps may be provided by
 481         the user at compile time by defining SK_ABORT.
 482
 483         On most platforms, allocating pixel memory may succeed even though there is
 484         not sufficient memory to hold pixels; allocation does not take place
 485         until the pixels are written to. The actual behavior depends on the platform
 486         implementation of malloc().
 487
 488         @param info      contains width, height, SkAlphaType, SkColorType, SkColorSpace
 489         @param rowBytes  size of pixel row or larger; may be zero
 490
 491         example: https://fiddle.skia.org/c/@Bitmap_allocPixels
 492     */
 493     void allocPixels(const SkImageInfo& info, size_t rowBytes);
 494
 495     /** Sets SkImageInfo to info following the rules in setInfo() and allocates pixel
 496         memory.
 497
 498         Returns false and calls reset() if SkImageInfo could not be set, or memory could
 499         not be allocated.
 500
 501         On most platforms, allocating pixel memory may succeed even though there is
 502         not sufficient memory to hold pixels; allocation does not take place
 503         until the pixels are written to. The actual behavior depends on the platform
 504         implementation of malloc().
 505
 506         @param info  contains width, height, SkAlphaType, SkColorType, SkColorSpace
 507         @return      true if pixel storage is allocated
 508     */
 509     bool SK_WARN_UNUSED_RESULT tryAllocPixels(const SkImageInfo& info) {
 510         return this->tryAllocPixels(info, info.minRowBytes());
 511     }
 512
 513     /** Sets SkImageInfo to info following the rules in setInfo() and allocates pixel
 514         memory.
 515
 516         Aborts execution if SkImageInfo could not be set, or memory could
 517         not be allocated. Abort steps may be provided by
 518         the user at compile time by defining SK_ABORT.
 519
 520         On most platforms, allocating pixel memory may succeed even though there is
 521         not sufficient memory to hold pixels; allocation does not take place
 522         until the pixels are written to. The actual behavior depends on the platform
 523         implementation of malloc().
 524
 525         @param info  contains width, height, SkAlphaType, SkColorType, SkColorSpace
 526
 527         example: https://fiddle.skia.org/c/@Bitmap_allocPixels_2
 528     */
 529     void allocPixels(const SkImageInfo& info);
 530
 531     /** Sets SkImageInfo to width, height, and native color type; and allocates
 532         pixel memory. If isOpaque is true, sets SkImageInfo to kOpaque_SkAlphaType;
 533         otherwise, sets to kPremul_SkAlphaType.
 534
 535         Calls reset() and returns false if width exceeds 29 bits or is negative,
 536         or height is negative.
 537
 538         Returns false if allocation fails.
 539
 540         Use to create SkBitmap that matches SkPMColor, the native pixel arrangement on
 541         the platform. SkBitmap drawn to output device skips converting its pixel format.
 542
 543         @param width     pixel column count; must be zero or greater
 544         @param height    pixel row count; must be zero or greater
 545         @param isOpaque  true if pixels do not have transparency
 546         @return          true if pixel storage is allocated
 547     */
 548     bool SK_WARN_UNUSED_RESULT tryAllocN32Pixels(int width, int height, bool isOpaque = false);
 549
 550     /** Sets SkImageInfo to width, height, and the native color type; and allocates
 551         pixel memory. If isOpaque is true, sets SkImageInfo to kOpaque_SkAlphaType;
 552         otherwise, sets to kPremul_SkAlphaType.
 553
 554         Aborts if width exceeds 29 bits or is negative, or height is negative, or
 555         allocation fails. Abort steps may be provided by the user at compile time by
 556         defining SK_ABORT.
 557
 558         Use to create SkBitmap that matches SkPMColor, the native pixel arrangement on
 559         the platform. SkBitmap drawn to output device skips converting its pixel format.
 560
 561         @param width     pixel column count; must be zero or greater
 562         @param height    pixel row count; must be zero or greater
 563         @param isOpaque  true if pixels do not have transparency
 564
 565         example: https://fiddle.skia.org/c/@Bitmap_allocN32Pixels
 566     */
 567     void allocN32Pixels(int width, int height, bool isOpaque = false);
 568
 569     /** Sets SkImageInfo to info following the rules in setInfo(), and creates SkPixelRef
 570         containing pixels and rowBytes. releaseProc, if not nullptr, is called
 571         immediately on failure or when pixels are no longer referenced. context may be
 572         nullptr.
 573
 574         If SkImageInfo could not be set, or rowBytes is less than info.minRowBytes():
 575         calls releaseProc if present, calls reset(), and returns false.
 576
 577         Otherwise, if pixels equals nullptr: sets SkImageInfo, calls releaseProc if
 578         present, returns true.
 579
 580         If SkImageInfo is set, pixels is not nullptr, and releaseProc is not nullptr:
 581         when pixels are no longer referenced, calls releaseProc with pixels and context
 582         as parameters.
 583
 584         @param info         contains width, height, SkAlphaType, SkColorType, SkColorSpace
 585         @param pixels       address or pixel storage; may be nullptr
 586         @param rowBytes     size of pixel row or larger
 587         @param releaseProc  function called when pixels can be deleted; may be nullptr
 588         @param context      caller state passed to releaseProc; may be nullptr
 589         @return             true if SkImageInfo is set to info
 590     */
 591     bool installPixels(const SkImageInfo& info, void* pixels, size_t rowBytes,
 592                        void (*releaseProc)(void* addr, void* context), void* context);
 593
 594     /** Sets SkImageInfo to info following the rules in setInfo(), and creates SkPixelRef
 595         containing pixels and rowBytes.
 596
 597         If SkImageInfo could not be set, or rowBytes is less than info.minRowBytes():
 598         calls reset(), and returns false.
 599
 600         Otherwise, if pixels equals nullptr: sets SkImageInfo, returns true.
 601
 602         Caller must ensure that pixels are valid for the lifetime of SkBitmap and SkPixelRef.
 603
 604         @param info      contains width, height, SkAlphaType, SkColorType, SkColorSpace
 605         @param pixels    address or pixel storage; may be nullptr
 606         @param rowBytes  size of pixel row or larger
 607         @return          true if SkImageInfo is set to info
 608     */
 609     bool installPixels(const SkImageInfo& info, void* pixels, size_t rowBytes) {
 610         return this->installPixels(info, pixels, rowBytes, nullptr, nullptr);
 611     }
 612
 613     /** Sets SkImageInfo to pixmap.info() following the rules in setInfo(), and creates
 614         SkPixelRef containing pixmap.addr() and pixmap.rowBytes().
 615
 616         If SkImageInfo could not be set, or pixmap.rowBytes() is less than
 617         SkImageInfo::minRowBytes(): calls reset(), and returns false.
 618
 619         Otherwise, if pixmap.addr() equals nullptr: sets SkImageInfo, returns true.
 620
 621         Caller must ensure that pixmap is valid for the lifetime of SkBitmap and SkPixelRef.
 622
 623         @param pixmap  SkImageInfo, pixel address, and rowBytes()
 624         @return        true if SkImageInfo was set to pixmap.info()
 625
 626         example: https://fiddle.skia.org/c/@Bitmap_installPixels_3
 627     */
 628     bool installPixels(const SkPixmap& pixmap);
 629
 630     /** Deprecated.
 631     */
 632     bool installMaskPixels(const SkMask& mask);
 633
 634     /** Replaces SkPixelRef with pixels, preserving SkImageInfo and rowBytes().
 635         Sets SkPixelRef origin to (0, 0).
 636
 637         If pixels is nullptr, or if info().colorType() equals kUnknown_SkColorType;
 638         release reference to SkPixelRef, and set SkPixelRef to nullptr.
 639
 640         Caller is responsible for handling ownership pixel memory for the lifetime
 641         of SkBitmap and SkPixelRef.
 642
 643         @param pixels  address of pixel storage, managed by caller
 644
 645         example: https://fiddle.skia.org/c/@Bitmap_setPixels
 646     */
 647     void setPixels(void* pixels);
 648
 649     /** Allocates pixel memory with HeapAllocator, and replaces existing SkPixelRef.
 650         The allocation size is determined by SkImageInfo width, height, and SkColorType.
 651
 652         Returns false if info().colorType() is kUnknown_SkColorType, or allocation fails.
 653
 654         @return  true if the allocation succeeds
 655     */
 656     bool SK_WARN_UNUSED_RESULT tryAllocPixels() {
 657         return this->tryAllocPixels((Allocator*)nullptr);
 658     }
 659
 660     /** Allocates pixel memory with HeapAllocator, and replaces existing SkPixelRef.
 661         The allocation size is determined by SkImageInfo width, height, and SkColorType.
 662
 663         Aborts if info().colorType() is kUnknown_SkColorType, or allocation fails.
 664         Abort steps may be provided by the user at compile
 665         time by defining SK_ABORT.
 666
 667         example: https://fiddle.skia.org/c/@Bitmap_allocPixels_3
 668     */
 669     void allocPixels();
 670
 671     /** Allocates pixel memory with allocator, and replaces existing SkPixelRef.
 672         The allocation size is determined by SkImageInfo width, height, and SkColorType.
 673         If allocator is nullptr, use HeapAllocator instead.
 674
 675         Returns false if Allocator::allocPixelRef return false.
 676
 677         @param allocator  instance of SkBitmap::Allocator instantiation
 678         @return           true if custom allocator reports success
 679     */
 680     bool SK_WARN_UNUSED_RESULT tryAllocPixels(Allocator* allocator);
 681
 682     /** Allocates pixel memory with allocator, and replaces existing SkPixelRef.
 683         The allocation size is determined by SkImageInfo width, height, and SkColorType.
 684         If allocator is nullptr, use HeapAllocator instead.
 685
 686         Aborts if Allocator::allocPixelRef return false. Abort steps may be provided by
 687         the user at compile time by defining SK_ABORT.
 688
 689         @param allocator  instance of SkBitmap::Allocator instantiation
 690
 691         example: https://fiddle.skia.org/c/@Bitmap_allocPixels_4
 692     */
 693     void allocPixels(Allocator* allocator);
 694
 695     /** Returns SkPixelRef, which contains: pixel base address; its dimensions; and
 696         rowBytes(), the interval from one row to the next. Does not change SkPixelRef
 697         reference count. SkPixelRef may be shared by multiple bitmaps.
 698         If SkPixelRef has not been set, returns nullptr.
 699
 700         @return  SkPixelRef, or nullptr
 701     */
 702     SkPixelRef* pixelRef() const { return fPixelRef.get(); }
 703
 704     /** Returns origin of pixels within SkPixelRef. SkBitmap bounds is always contained
 705         by SkPixelRef bounds, which may be the same size or larger. Multiple SkBitmap
 706         can share the same SkPixelRef, where each SkBitmap has different bounds.
 707
 708         The returned origin added to SkBitmap dimensions equals or is smaller than the
 709         SkPixelRef dimensions.
 710
 711         Returns (0, 0) if SkPixelRef is nullptr.
 712
 713         @return  pixel origin within SkPixelRef
 714
 715         example: https://fiddle.skia.org/c/@Bitmap_pixelRefOrigin
 716     */
 717     SkIPoint pixelRefOrigin() const;
 718
 719     /** Replaces pixelRef and origin in SkBitmap.  dx and dy specify the offset
 720         within the SkPixelRef pixels for the top-left corner of the bitmap.
 721
 722         Asserts in debug builds if dx or dy are out of range. Pins dx and dy
 723         to legal range in release builds.
 724
 725         The caller is responsible for ensuring that the pixels match the
 726         SkColorType and SkAlphaType in SkImageInfo.
 727
 728         @param pixelRef  SkPixelRef describing pixel address and rowBytes()
 729         @param dx        column offset in SkPixelRef for bitmap origin
 730         @param dy        row offset in SkPixelRef for bitmap origin
 731
 732         example: https://fiddle.skia.org/c/@Bitmap_setPixelRef
 733     */
 734     void setPixelRef(sk_sp<SkPixelRef> pixelRef, int dx, int dy);
 735
 736     /** Returns true if SkBitmap is can be drawn.
 737
 738         @return  true if getPixels() is not nullptr
 739     */
 740     bool readyToDraw() const {
 741         return this->getPixels() != nullptr;
 742     }
 743
 744     /** Returns a unique value corresponding to the pixels in SkPixelRef.
 745         Returns a different value after notifyPixelsChanged() has been called.
 746         Returns zero if SkPixelRef is nullptr.
 747
 748         Determines if pixels have changed since last examined.
 749
 750         @return  unique value for pixels in SkPixelRef
 751
 752         example: https://fiddle.skia.org/c/@Bitmap_getGenerationID
 753     */
 754     uint32_t getGenerationID() const;
 755
 756     /** Marks that pixels in SkPixelRef have changed. Subsequent calls to
 757         getGenerationID() return a different value.
 758
 759         example: https://fiddle.skia.org/c/@Bitmap_notifyPixelsChanged
 760     */
 761     void notifyPixelsChanged() const;
 762
 763     /** Replaces pixel values with c, interpreted as being in the sRGB SkColorSpace.
 764         All pixels contained by bounds() are affected. If the colorType() is
 765         kGray_8_SkColorType or kRGB_565_SkColorType, then alpha is ignored; RGB is
 766         treated as opaque. If colorType() is kAlpha_8_SkColorType, then RGB is ignored.
 767
 768         @param c            unpremultiplied color
 769         @param colorSpace   SkColorSpace of c
 770
 771         example: https://fiddle.skia.org/c/@Bitmap_eraseColor
 772     */
 773     void eraseColor(SkColor4f c, SkColorSpace* colorSpace = nullptr) const;
 774
 775     /** Replaces pixel values with c, interpreted as being in the sRGB SkColorSpace.
 776         All pixels contained by bounds() are affected. If the colorType() is
 777         kGray_8_SkColorType or kRGB_565_SkColorType, then alpha is ignored; RGB is
 778         treated as opaque. If colorType() is kAlpha_8_SkColorType, then RGB is ignored.
 779
 780         Input color is ultimately converted to an SkColor4f, so eraseColor(SkColor4f c)
 781         will have higher color resolution.
 782
 783         @param c  unpremultiplied color.
 784
 785         example: https://fiddle.skia.org/c/@Bitmap_eraseColor
 786     */
 787     void eraseColor(SkColor c) const;
 788
 789     /** Replaces pixel values with unpremultiplied color built from a, r, g, and b,
 790         interpreted as being in the sRGB SkColorSpace. All pixels contained by
 791         bounds() are affected. If the colorType() is kGray_8_SkColorType or
 792         kRGB_565_SkColorType, then a is ignored; r, g, and b are treated as opaque.
 793         If colorType() is kAlpha_8_SkColorType, then r, g, and b are ignored.
 794
 795         @param a  amount of alpha, from fully transparent (0) to fully opaque (255)
 796         @param r  amount of red, from no red (0) to full red (255)
 797         @param g  amount of green, from no green (0) to full green (255)
 798         @param b  amount of blue, from no blue (0) to full blue (255)
 799     */
 800     void eraseARGB(U8CPU a, U8CPU r, U8CPU g, U8CPU b) const {
 801         this->eraseColor(SkColorSetARGB(a, r, g, b));
 802     }
 803
 804     /** Replaces pixel values inside area with c. interpreted as being in the sRGB
 805         SkColorSpace. If area does not intersect bounds(), call has no effect.
 806
 807         If the colorType() is kGray_8_SkColorType or kRGB_565_SkColorType, then alpha
 808         is ignored; RGB is treated as opaque. If colorType() is kAlpha_8_SkColorType,
 809         then RGB is ignored.
 810
 811         @param c            unpremultiplied color
 812         @param area         rectangle to fill
 813         @param colorSpace   SkColorSpace of c
 814
 815         example: https://fiddle.skia.org/c/@Bitmap_erase
 816     */
 817     void erase(SkColor4f c, SkColorSpace* colorSpace, const SkIRect& area) const;
 818     void erase(SkColor4f c, const SkIRect& area) const;
 819
 820     /** Replaces pixel values inside area with c. interpreted as being in the sRGB
 821         SkColorSpace. If area does not intersect bounds(), call has no effect.
 822
 823         If the colorType() is kGray_8_SkColorType or kRGB_565_SkColorType, then alpha
 824         is ignored; RGB is treated as opaque. If colorType() is kAlpha_8_SkColorType,
 825         then RGB is ignored.
 826
 827         Input color is ultimately converted to an SkColor4f, so erase(SkColor4f c)
 828         will have higher color resolution.
 829
 830         @param c     unpremultiplied color
 831         @param area  rectangle to fill
 832
 833         example: https://fiddle.skia.org/c/@Bitmap_erase
 834     */
 835     void erase(SkColor c, const SkIRect& area) const;
 836
 837     /** Deprecated.
 838     */
 839     void eraseArea(const SkIRect& area, SkColor c) const {
 840         this->erase(c, area);
 841     }
 842
 843     /** Returns pixel at (x, y) as unpremultiplied color.
 844         Returns black with alpha if SkColorType is kAlpha_8_SkColorType.
 845
 846         Input is not validated: out of bounds values of x or y trigger an assert() if
 847         built with SK_DEBUG defined; and returns undefined values or may crash if
 848         SK_RELEASE is defined. Fails if SkColorType is kUnknown_SkColorType or
 849         pixel address is nullptr.
 850
 851         SkColorSpace in SkImageInfo is ignored. Some color precision may be lost in the
 852         conversion to unpremultiplied color; original pixel data may have additional
 853         precision.
 854
 855         @param x  column index, zero or greater, and less than width()
 856         @param y  row index, zero or greater, and less than height()
 857         @return   pixel converted to unpremultiplied color
 858     */
 859     SkColor getColor(int x, int y) const {
 860         return this->pixmap().getColor(x, y);
 861     }
 862
 863     /** Look up the pixel at (x,y) and return its alpha component, normalized to [0..1].
 864         This is roughly equivalent to SkGetColorA(getColor()), but can be more efficent
 865         (and more precise if the pixels store more than 8 bits per component).
 866
 867         @param x  column index, zero or greater, and less than width()
 868         @param y  row index, zero or greater, and less than height()
 869         @return   alpha converted to normalized float
 870      */
 871     float getAlphaf(int x, int y) const {
 872         return this->pixmap().getAlphaf(x, y);
 873     }
 874
 875     /** Returns pixel address at (x, y).
 876
 877         Input is not validated: out of bounds values of x or y, or kUnknown_SkColorType,
 878         trigger an assert() if built with SK_DEBUG defined. Returns nullptr if
 879         SkColorType is kUnknown_SkColorType, or SkPixelRef is nullptr.
 880
 881         Performs a lookup of pixel size; for better performance, call
 882         one of: getAddr8(), getAddr16(), or getAddr32().
 883
 884         @param x  column index, zero or greater, and less than width()
 885         @param y  row index, zero or greater, and less than height()
 886         @return   generic pointer to pixel
 887
 888         example: https://fiddle.skia.org/c/@Bitmap_getAddr
 889     */
 890     void* getAddr(int x, int y) const;
 891
 892     /** Returns address at (x, y).
 893
 894         Input is not validated. Triggers an assert() if built with SK_DEBUG defined and:
 895         - SkPixelRef is nullptr
 896         - bytesPerPixel() is not four
 897         - x is negative, or not less than width()
 898         - y is negative, or not less than height()
 899
 900         @param x  column index, zero or greater, and less than width()
 901         @param y  row index, zero or greater, and less than height()
 902         @return   unsigned 32-bit pointer to pixel at (x, y)
 903     */
 904     inline uint32_t* getAddr32(int x, int y) const;
 905
 906     /** Returns address at (x, y).
 907
 908         Input is not validated. Triggers an assert() if built with SK_DEBUG defined and:
 909         - SkPixelRef is nullptr
 910         - bytesPerPixel() is not two
 911         - x is negative, or not less than width()
 912         - y is negative, or not less than height()
 913
 914         @param x  column index, zero or greater, and less than width()
 915         @param y  row index, zero or greater, and less than height()
 916         @return   unsigned 16-bit pointer to pixel at (x, y)
 917     */
 918     inline uint16_t* getAddr16(int x, int y) const;
 919
 920     /** Returns address at (x, y).
 921
 922         Input is not validated. Triggers an assert() if built with SK_DEBUG defined and:
 923         - SkPixelRef is nullptr
 924         - bytesPerPixel() is not one
 925         - x is negative, or not less than width()
 926         - y is negative, or not less than height()
 927
 928         @param x  column index, zero or greater, and less than width()
 929         @param y  row index, zero or greater, and less than height()
 930         @return   unsigned 8-bit pointer to pixel at (x, y)
 931     */
 932     inline uint8_t* getAddr8(int x, int y) const;
 933
 934     /** Shares SkPixelRef with dst. Pixels are not copied; SkBitmap and dst point
 935         to the same pixels; dst bounds() are set to the intersection of subset
 936         and the original bounds().
 937
 938         subset may be larger than bounds(). Any area outside of bounds() is ignored.
 939
 940         Any contents of dst are discarded.
 941
 942         Return false if:
 943         - dst is nullptr
 944         - SkPixelRef is nullptr
 945         - subset does not intersect bounds()
 946
 947         @param dst     SkBitmap set to subset
 948         @param subset  rectangle of pixels to reference
 949         @return        true if dst is replaced by subset
 950
 951         example: https://fiddle.skia.org/c/@Bitmap_extractSubset
 952     */
 953     bool extractSubset(SkBitmap* dst, const SkIRect& subset) const;
 954
 955     /** Copies a SkRect of pixels from SkBitmap to dstPixels. Copy starts at (srcX, srcY),
 956         and does not exceed SkBitmap (width(), height()).
 957
 958         dstInfo specifies width, height, SkColorType, SkAlphaType, and SkColorSpace of
 959         destination. dstRowBytes specifics the gap from one destination row to the next.
 960         Returns true if pixels are copied. Returns false if:
 961         - dstInfo has no address
 962         - dstRowBytes is less than dstInfo.minRowBytes()
 963         - SkPixelRef is nullptr
 964
 965         Pixels are copied only if pixel conversion is possible. If SkBitmap colorType() is
 966         kGray_8_SkColorType, or kAlpha_8_SkColorType; dstInfo.colorType() must match.
 967         If SkBitmap colorType() is kGray_8_SkColorType, dstInfo.colorSpace() must match.
 968         If SkBitmap alphaType() is kOpaque_SkAlphaType, dstInfo.alphaType() must
 969         match. If SkBitmap colorSpace() is nullptr, dstInfo.colorSpace() must match. Returns
 970         false if pixel conversion is not possible.
 971
 972         srcX and srcY may be negative to copy only top or left of source. Returns
 973         false if width() or height() is zero or negative.
 974         Returns false if abs(srcX) >= Bitmap width(), or if abs(srcY) >= Bitmap height().
 975
 976         @param dstInfo      destination width, height, SkColorType, SkAlphaType, SkColorSpace
 977         @param dstPixels    destination pixel storage
 978         @param dstRowBytes  destination row length
 979         @param srcX         column index whose absolute value is less than width()
 980         @param srcY         row index whose absolute value is less than height()
 981         @return             true if pixels are copied to dstPixels
 982     */
 983     bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes,
 984                     int srcX, int srcY) const;
 985
 986     /** Copies a SkRect of pixels from SkBitmap to dst. Copy starts at (srcX, srcY), and
 987         does not exceed SkBitmap (width(), height()).
 988
 989         dst specifies width, height, SkColorType, SkAlphaType, SkColorSpace, pixel storage,
 990         and row bytes of destination. dst.rowBytes() specifics the gap from one destination
 991         row to the next. Returns true if pixels are copied. Returns false if:
 992         - dst pixel storage equals nullptr
 993         - dst.rowBytes is less than SkImageInfo::minRowBytes()
 994         - SkPixelRef is nullptr
 995
 996         Pixels are copied only if pixel conversion is possible. If SkBitmap colorType() is
 997         kGray_8_SkColorType, or kAlpha_8_SkColorType; dst SkColorType must match.
 998         If SkBitmap colorType() is kGray_8_SkColorType, dst SkColorSpace must match.
 999         If SkBitmap alphaType() is kOpaque_SkAlphaType, dst SkAlphaType must
1000         match. If SkBitmap colorSpace() is nullptr, dst SkColorSpace must match. Returns
1001         false if pixel conversion is not possible.
1002
1003         srcX and srcY may be negative to copy only top or left of source. Returns
1004         false if width() or height() is zero or negative.
1005         Returns false if abs(srcX) >= Bitmap width(), or if abs(srcY) >= Bitmap height().
1006
1007         @param dst   destination SkPixmap: SkImageInfo, pixels, row bytes
1008         @param srcX  column index whose absolute value is less than width()
1009         @param srcY  row index whose absolute value is less than height()
1010         @return      true if pixels are copied to dst
1011
1012         example: https://fiddle.skia.org/c/@Bitmap_readPixels_2
1013     */
1014     bool readPixels(const SkPixmap& dst, int srcX, int srcY) const;
1015
1016     /** Copies a SkRect of pixels from SkBitmap to dst. Copy starts at (0, 0), and
1017         does not exceed SkBitmap (width(), height()).
1018
1019         dst specifies width, height, SkColorType, SkAlphaType, SkColorSpace, pixel storage,
1020         and row bytes of destination. dst.rowBytes() specifics the gap from one destination
1021         row to the next. Returns true if pixels are copied. Returns false if:
1022         - dst pixel storage equals nullptr
1023         - dst.rowBytes is less than SkImageInfo::minRowBytes()
1024         - SkPixelRef is nullptr
1025
1026         Pixels are copied only if pixel conversion is possible. If SkBitmap colorType() is
1027         kGray_8_SkColorType, or kAlpha_8_SkColorType; dst SkColorType must match.
1028         If SkBitmap colorType() is kGray_8_SkColorType, dst SkColorSpace must match.
1029         If SkBitmap alphaType() is kOpaque_SkAlphaType, dst SkAlphaType must
1030         match. If SkBitmap colorSpace() is nullptr, dst SkColorSpace must match. Returns
1031         false if pixel conversion is not possible.
1032
1033         @param dst  destination SkPixmap: SkImageInfo, pixels, row bytes
1034         @return     true if pixels are copied to dst
1035     */
1036     bool readPixels(const SkPixmap& dst) const {
1037         return this->readPixels(dst, 0, 0);
1038     }
1039
1040     /** Copies a SkRect of pixels from src. Copy starts at (dstX, dstY), and does not exceed
1041         (src.width(), src.height()).
1042
1043         src specifies width, height, SkColorType, SkAlphaType, SkColorSpace, pixel storage,
1044         and row bytes of source. src.rowBytes() specifics the gap from one source
1045         row to the next. Returns true if pixels are copied. Returns false if:
1046         - src pixel storage equals nullptr
1047         - src.rowBytes is less than SkImageInfo::minRowBytes()
1048         - SkPixelRef is nullptr
1049
1050         Pixels are copied only if pixel conversion is possible. If SkBitmap colorType() is
1051         kGray_8_SkColorType, or kAlpha_8_SkColorType; src SkColorType must match.
1052         If SkBitmap colorType() is kGray_8_SkColorType, src SkColorSpace must match.
1053         If SkBitmap alphaType() is kOpaque_SkAlphaType, src SkAlphaType must
1054         match. If SkBitmap colorSpace() is nullptr, src SkColorSpace must match. Returns
1055         false if pixel conversion is not possible.
1056
1057         dstX and dstY may be negative to copy only top or left of source. Returns
1058         false if width() or height() is zero or negative.
1059         Returns false if abs(dstX) >= Bitmap width(), or if abs(dstY) >= Bitmap height().
1060
1061         @param src   source SkPixmap: SkImageInfo, pixels, row bytes
1062         @param dstX  column index whose absolute value is less than width()
1063         @param dstY  row index whose absolute value is less than height()
1064         @return      true if src pixels are copied to SkBitmap
1065
1066         example: https://fiddle.skia.org/c/@Bitmap_writePixels
1067     */
1068     bool writePixels(const SkPixmap& src, int dstX, int dstY);
1069
1070     /** Copies a SkRect of pixels from src. Copy starts at (0, 0), and does not exceed
1071         (src.width(), src.height()).
1072
1073         src specifies width, height, SkColorType, SkAlphaType, SkColorSpace, pixel storage,
1074         and row bytes of source. src.rowBytes() specifics the gap from one source
1075         row to the next. Returns true if pixels are copied. Returns false if:
1076         - src pixel storage equals nullptr
1077         - src.rowBytes is less than SkImageInfo::minRowBytes()
1078         - SkPixelRef is nullptr
1079
1080         Pixels are copied only if pixel conversion is possible. If SkBitmap colorType() is
1081         kGray_8_SkColorType, or kAlpha_8_SkColorType; src SkColorType must match.
1082         If SkBitmap colorType() is kGray_8_SkColorType, src SkColorSpace must match.
1083         If SkBitmap alphaType() is kOpaque_SkAlphaType, src SkAlphaType must
1084         match. If SkBitmap colorSpace() is nullptr, src SkColorSpace must match. Returns
1085         false if pixel conversion is not possible.
1086
1087         @param src  source SkPixmap: SkImageInfo, pixels, row bytes
1088         @return     true if src pixels are copied to SkBitmap
1089     */
1090     bool writePixels(const SkPixmap& src) {
1091         return this->writePixels(src, 0, 0);
1092     }
1093
1094     /** Sets dst to alpha described by pixels. Returns false if dst cannot be written to
1095         or dst pixels cannot be allocated.
1096
1097         Uses HeapAllocator to reserve memory for dst SkPixelRef.
1098
1099         @param dst  holds SkPixelRef to fill with alpha layer
1100         @return     true if alpha layer was constructed in dst SkPixelRef
1101     */
1102     bool extractAlpha(SkBitmap* dst) const {
1103         return this->extractAlpha(dst, nullptr, nullptr, nullptr);
1104     }
1105
1106     /** Sets dst to alpha described by pixels. Returns false if dst cannot be written to
1107         or dst pixels cannot be allocated.
1108
1109         If paint is not nullptr and contains SkMaskFilter, SkMaskFilter
1110         generates mask alpha from SkBitmap. Uses HeapAllocator to reserve memory for dst
1111         SkPixelRef. Sets offset to top-left position for dst for alignment with SkBitmap;
1112         (0, 0) unless SkMaskFilter generates mask.
1113
1114         @param dst     holds SkPixelRef to fill with alpha layer
1115         @param paint   holds optional SkMaskFilter; may be nullptr
1116         @param offset  top-left position for dst; may be nullptr
1117         @return        true if alpha layer was constructed in dst SkPixelRef
1118     */
1119     bool extractAlpha(SkBitmap* dst, const SkPaint* paint,
1120                       SkIPoint* offset) const {
1121         return this->extractAlpha(dst, paint, nullptr, offset);
1122     }
1123
1124     /** Sets dst to alpha described by pixels. Returns false if dst cannot be written to
1125         or dst pixels cannot be allocated.
1126
1127         If paint is not nullptr and contains SkMaskFilter, SkMaskFilter
1128         generates mask alpha from SkBitmap. allocator may reference a custom allocation
1129         class or be set to nullptr to use HeapAllocator. Sets offset to top-left
1130         position for dst for alignment with SkBitmap; (0, 0) unless SkMaskFilter generates
1131         mask.
1132
1133         @param dst        holds SkPixelRef to fill with alpha layer
1134         @param paint      holds optional SkMaskFilter; may be nullptr
1135         @param allocator  function to reserve memory for SkPixelRef; may be nullptr
1136         @param offset     top-left position for dst; may be nullptr
1137         @return           true if alpha layer was constructed in dst SkPixelRef
1138     */
1139     bool extractAlpha(SkBitmap* dst, const SkPaint* paint, Allocator* allocator,
1140                       SkIPoint* offset) const;
1141
1142     /** Copies SkBitmap pixel address, row bytes, and SkImageInfo to pixmap, if address
1143         is available, and returns true. If pixel address is not available, return
1144         false and leave pixmap unchanged.
1145
1146         pixmap contents become invalid on any future change to SkBitmap.
1147
1148         @param pixmap  storage for pixel state if pixels are readable; otherwise, ignored
1149         @return        true if SkBitmap has direct access to pixels
1150
1151         example: https://fiddle.skia.org/c/@Bitmap_peekPixels
1152     */
1153     bool peekPixels(SkPixmap* pixmap) const;
1154     sk_sp<SkShader> makeShader(SkTileMode tmx, SkTileMode tmy, const SkSamplingOptions&,
1155                                const SkMatrix* = nullptr) const;
1156
1157     sk_sp<SkShader> makeShader(SkTileMode tmx, SkTileMode tmy, const SkSamplingOptions& sampling,
1158                                const SkMatrix& localMatrix) const {
1159         return this->makeShader(tmx, tmy, sampling, &localMatrix);
1160     }
1161
1162     sk_sp<SkShader> makeShader(const SkSamplingOptions& sampling,
1163                                const SkMatrix* localMatrix = nullptr) const {
1164         return this->makeShader(SkTileMode::kClamp, SkTileMode::kClamp, sampling, localMatrix);
1165     }
1166
1167     sk_sp<SkShader> makeShader(const SkSamplingOptions& sampling,
1168                                const SkMatrix& localMatrix) const {
1169         return this->makeShader(sampling, &localMatrix);
1170     }
1171
1172     /**
1173      *  Returns a new image from the bitmap. If the bitmap is marked immutable, this will
1174      *  share the pixel buffer. If not, it will make a copy of the pixels for the image.
1175      */
1176     sk_sp<SkImage> asImage() const;
1177
1178     /** Asserts if internal values are illegal or inconsistent. Only available if
1179         SK_DEBUG is defined at compile time.
1180     */
1181     SkDEBUGCODE(void validate() const;)
1182
1183     /** \class SkBitmap::Allocator
1184         Abstract subclass of HeapAllocator.
1185     */
1186     class Allocator : public SkRefCnt {
1187     public:
1188
1189         /** Allocates the pixel memory for the bitmap, given its dimensions and
1190             SkColorType. Returns true on success, where success means either setPixels()
1191             or setPixelRef() was called.
1192
1193             @param bitmap  SkBitmap containing SkImageInfo as input, and SkPixelRef as output
1194             @return        true if SkPixelRef was allocated
1195         */
1196         virtual bool allocPixelRef(SkBitmap* bitmap) = 0;
1197     private:
1198         using INHERITED = SkRefCnt;
1199     };
1200
1201     /** \class SkBitmap::HeapAllocator
1202         Subclass of SkBitmap::Allocator that returns a SkPixelRef that allocates its pixel
1203         memory from the heap. This is the default SkBitmap::Allocator invoked by
1204         allocPixels().
1205     */
1206     class HeapAllocator : public Allocator {
1207     public:
1208
1209         /** Allocates the pixel memory for the bitmap, given its dimensions and
1210             SkColorType. Returns true on success, where success means either setPixels()
1211             or setPixelRef() was called.
1212
1213             @param bitmap  SkBitmap containing SkImageInfo as input, and SkPixelRef as output
1214             @return        true if pixels are allocated
1215
1216         example: https://fiddle.skia.org/c/@Bitmap_HeapAllocator_allocPixelRef
1217         */
1218         bool allocPixelRef(SkBitmap* bitmap) override;
1219     };
1220
1221 private:
1222     sk_sp<SkPixelRef>   fPixelRef;
1223     SkPixmap            fPixmap;
1224     sk_sp<SkMipmap>     fMips;
1225
1226     friend class SkImage_Raster;
1227     friend class SkReadBuffer;        // unflatten
1228     friend class GrProxyProvider;     // fMips
1229 };
1230
1231 ///////////////////////////////////////////////////////////////////////////////
1232
1233 inline uint32_t* SkBitmap::getAddr32(int x, int y) const {
1234     SkASSERT(fPixmap.addr());
1235     return fPixmap.writable_addr32(x, y);
1236 }
1237
1238 inline uint16_t* SkBitmap::getAddr16(int x, int y) const {
1239     SkASSERT(fPixmap.addr());
1240     return fPixmap.writable_addr16(x, y);
1241 }
1242
1243 inline uint8_t* SkBitmap::getAddr8(int x, int y) const {
1244     SkASSERT(fPixmap.addr());
1245     return fPixmap.writable_addr8(x, y);
1246 }
1247
1248 #endif