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