• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1#Topic Pixmap
2#Alias Pixmap_Reference
3
4#Subtopic Overview
5    #Subtopic Subtopic
6    #Populate
7    ##
8##
9
10#Class SkPixmap
11
12Pixmap provides a utility to pair SkImageInfo with pixels and row bytes.
13Pixmap is a low level class which provides convenience functions to access
14raster destinations. Canvas can not draw Pixmap, nor does Pixmap provide
15a direct drawing destination.
16
17Use Bitmap to draw pixels referenced by Pixmap; use Surface to draw into
18pixels referenced by Pixmap.
19
20Pixmap does not try to manage the lifetime of the pixel memory. Use Pixel_Ref
21to manage pixel memory; Pixel_Ref is safe across threads.
22
23#Subtopic Related_Function
24#Populate
25##
26
27#Subtopic Constructor
28#Populate
29##
30
31#Subtopic Member_Function
32#Populate
33##
34
35#Subtopic Initialization
36#Line # sets fields for use ##
37
38# ------------------------------------------------------------------------------
39
40#Method SkPixmap()
41
42#In Initialization
43#Line # constructs with default values ##
44Creates an empty Pixmap without pixels, with kUnknown_SkColorType, with
45kUnknown_SkAlphaType, and with a width and height of zero. Use
46reset() to associate pixels, SkColorType, SkAlphaType, width, and height
47after Pixmap has been created.
48
49#Return empty Pixmap ##
50
51#Example
52void draw(SkCanvas* canvas) {
53    const char* alphas[] = {"Unknown", "Opaque", "Premul", "Unpremul"};
54    const char* colors[] = {"Unknown", "Alpha_8", "RGB_565", "ARGB_4444", "RGBA_8888", "RGB_888x",
55                            "BGRA_8888", "RGBA_1010102", "RGB_101010x", "Gray_8", "RGBA_F16"};
56    SkPixmap pixmap;
57    for (int i = 0; i < 2; ++i) {
58       SkDebugf("width: %2d  height: %2d", pixmap.width(), pixmap.height());
59       SkDebugf("  color: k%s_SkColorType", colors[pixmap.colorType()]);
60       SkDebugf("  alpha: k%s_SkAlphaType\n", alphas[pixmap.alphaType()]);
61       pixmap.reset(SkImageInfo::Make(25, 35, kRGBA_8888_SkColorType, kOpaque_SkAlphaType),
62                    nullptr, 0);
63    }
64}
65#StdOut
66width:  0  height:  0  color: kUnknown_SkColorType  alpha: kUnknown_SkAlphaType
67width: 25  height: 35  color: kRGBA_8888_SkColorType  alpha: kOpaque_SkAlphaType
68##
69##
70
71#SeeAlso SkPixmap(const SkImageInfo& info, const void* addr, size_t rowBytes) reset() SkAlphaType SkColorType
72
73##
74
75# ------------------------------------------------------------------------------
76
77#Method SkPixmap(const SkImageInfo& info, const void* addr, size_t rowBytes)
78
79#In Initialization
80#Line # constructs from Image_Info, pixels ##
81Creates Pixmap from info width, height, SkAlphaType, and SkColorType.
82addr points to pixels, or nullptr. rowBytes should be info.width() times
83info.bytesPerPixel(), or larger.
84
85No parameter checking is performed; it is up to the caller to ensure that
86addr and rowBytes agree with info.
87
88The memory lifetime of pixels is managed by the caller. When Pixmap goes
89out of scope, addr is unaffected.
90
91Pixmap may be later modified by reset() to change its size, pixel type, or
92storage.
93
94#Param info  width, height, SkAlphaType, SkColorType of Image_Info ##
95#Param addr  pointer to pixels allocated by caller; may be nullptr ##
96#Param rowBytes  size of one row of addr; width times pixel size, or larger ##
97
98#Return initialized Pixmap ##
99
100#Example
101#Image 3
102#Description
103SkImage::MakeRasterCopy takes const SkPixmap& as an argument. The example
104constructs a SkPixmap from the brace-delimited parameters.
105##
106    SkDebugf("image alpha only = %s\n", image->isAlphaOnly() ? "true" : "false");
107    SkPMColor pmColors = 0;
108    sk_sp<SkImage> copy = SkImage::MakeRasterCopy({SkImageInfo::MakeA8(1, 1),
109                                                  (uint8_t*)&pmColors,
110                                                  1});
111    SkDebugf("copy alpha only = %s\n", copy->isAlphaOnly() ? "true" : "false");
112#StdOut
113image alpha only = false
114copy alpha only = true
115##
116##
117
118#SeeAlso SkPixmap() reset() SkAlphaType SkColorType
119
120##
121
122# ------------------------------------------------------------------------------
123
124#Method void reset()
125
126#In Initialization
127#Line # reuses existing Pixmap with replacement values ##
128Sets width, height, row bytes to zero; pixel address to nullptr; SkColorType to
129kUnknown_SkColorType; and SkAlphaType to kUnknown_SkAlphaType.
130
131The prior pixels are unaffected; it is up to the caller to release pixels
132memory if desired.
133
134#Example
135void draw(SkCanvas* canvas) {
136    const char* alphas[] = {"Unknown", "Opaque", "Premul", "Unpremul"};
137    const char* colors[] = {"Unknown", "Alpha_8", "RGB_565", "ARGB_4444", "RGBA_8888", "RGB_888x",
138                            "BGRA_8888", "RGBA_1010102", "RGB_101010x", "Gray_8", "RGBA_F16"};
139    SkPixmap pixmap(SkImageInfo::Make(25, 35, kRGBA_8888_SkColorType, kOpaque_SkAlphaType),
140                    nullptr, 0);
141    for (int i = 0; i < 2; ++i) {
142       SkDebugf("width: %2d  height: %2d", pixmap.width(), pixmap.height());
143       SkDebugf("  color: k%s_SkColorType", colors[pixmap.colorType()]);
144       SkDebugf("  alpha: k%s_SkAlphaType\n", alphas[pixmap.alphaType()]);
145       pixmap.reset();
146    }
147}
148#StdOut
149width: 25  height: 35  color: kRGBA_8888_SkColorType  alpha: kOpaque_SkAlphaType
150width:  0  height:  0  color: kUnknown_SkColorType  alpha: kUnknown_SkAlphaType
151##
152##
153
154#SeeAlso SkPixmap() SkAlphaType SkColorType
155
156##
157
158# ------------------------------------------------------------------------------
159
160#Method void reset(const SkImageInfo& info, const void* addr, size_t rowBytes)
161
162#In Initialization
163Sets width, height, SkAlphaType, and SkColorType from info.
164Sets pixel address from addr, which may be nullptr.
165Sets row bytes from rowBytes, which should be info.width() times
166info.bytesPerPixel(), or larger.
167
168Does not check addr. Asserts if built with SK_DEBUG defined and if rowBytes is
169too small to hold one row of pixels.
170
171The memory lifetime pixels are managed by the caller. When Pixmap goes
172out of scope, addr is unaffected.
173
174#Param info  width, height, SkAlphaType, SkColorType of Image_Info ##
175#Param addr  pointer to pixels allocated by caller; may be nullptr ##
176#Param rowBytes  size of one row of addr; width times pixel size, or larger ##
177
178#Example
179#Image 4
180#Height 64
181void draw(SkCanvas* canvas) {
182    std::vector<int32_t> pixels;
183    pixels.resize(image->height() * image->width() * 4);
184    SkPixmap pixmap(SkImageInfo::Make(image->width(), image->height(), kN32_SkColorType,
185            image->alphaType()), (const void*) &pixels.front(), image->width() * 4);
186    image->readPixels(pixmap, 0, 0);
187    int x = 0;
188    for (auto colorType : { kRGBA_8888_SkColorType, kBGRA_8888_SkColorType } ) {
189        pixmap.reset(SkImageInfo::Make(image->width(), image->height(), colorType,
190                image->alphaType()), (const void*) &pixels.front(), image->width() * 4);
191        SkBitmap bitmap;
192        bitmap.installPixels(pixmap);
193        canvas->drawBitmap(bitmap, x, 0);
194        x += 128;
195    }
196}
197##
198
199#SeeAlso SkPixmap(const SkImageInfo& info, const void* addr, size_t rowBytes) reset() SkAlphaType SkColorType
200
201##
202
203# ------------------------------------------------------------------------------
204
205#Method void setColorSpace(sk_sp<SkColorSpace> colorSpace)
206
207#In Initialization
208#Line # sets Image_Info Color_Space ##
209
210Changes Color_Space in Image_Info; preserves width, height, SkAlphaType, and
211SkColorType in Image, and leaves pixel address and row bytes unchanged.
212Color_Space reference count is incremented.
213
214#Param colorSpace  Color_Space moved to Image_Info ##
215
216#Example
217void draw(SkCanvas* canvas) {
218    SkPixmap pixmap;
219    sk_sp<SkColorSpace> colorSpace1 = SkColorSpace::MakeRGB(SkColorSpace::kLinear_RenderTargetGamma,
220                                                            SkColorSpace::kRec2020_Gamut);
221    SkDebugf("is %sunique\n", colorSpace1->unique() ? "" : "not ");
222    pixmap.setColorSpace(colorSpace1);
223    SkDebugf("is %sunique\n", colorSpace1->unique() ? "" : "not ");
224}
225#StdOut
226is unique
227is not unique
228##
229##
230
231#SeeAlso Color_Space SkImageInfo::makeColorSpace
232
233##
234
235# ------------------------------------------------------------------------------
236
237#Method bool SK_WARN_UNUSED_RESULT reset(const SkMask& mask)
238#Deprecated soon
239##
240
241# ------------------------------------------------------------------------------
242
243#Method bool SK_WARN_UNUSED_RESULT extractSubset(SkPixmap* subset, const SkIRect& area) const
244
245#In Initialization
246#Line # sets pointer to portion of original ##
247Sets subset width, height, pixel address to intersection of Pixmap with area,
248if intersection is not empty; and return true. Otherwise, leave subset unchanged
249and return false.
250
251Failing to read the return value generates a compile time warning.
252
253#Param subset  storage for width, height, pixel address of intersection ##
254#Param area    bounds to intersect with Pixmap ##
255
256#Return true if intersection of Pixmap and area is not empty ##
257
258#Example
259#Image 3
260#Height 128
261void draw(SkCanvas* canvas) {
262    std::vector<int32_t> pixels;
263    pixels.resize(image->height() * image->width() * 4);
264    SkPixmap pixmap(SkImageInfo::Make(image->width(), image->height(), kN32_SkColorType,
265            image->alphaType()), (const void*) &pixels.front(), image->width() * 4);
266    image->readPixels(pixmap, 0, 0);
267    SkPixmap inset;
268    if (pixmap.extractSubset(&inset, {128, 128, 512, 512})) {
269        SkBitmap bitmap;
270        bitmap.installPixels(inset);
271        canvas->drawBitmap(bitmap, 0, 0);
272    }
273}
274##
275
276#SeeAlso reset() SkIRect::intersect
277
278##
279
280#Subtopic Initialization ##
281
282#Subtopic Image_Info_Access
283#Line # returns all or part of Image_Info ##
284
285# ------------------------------------------------------------------------------
286
287#Method const SkImageInfo& info() const
288
289#In Image_Info_Access
290#Line # returns Image_Info ##
291Returns width, height, Alpha_Type, Color_Type, and Color_Space.
292
293#Return reference to ImageInfo  ##
294
295#Example
296#Image 3
297    std::vector<int32_t> pixels;
298    pixels.resize(image->height() * image->width() * 4);
299    SkPixmap pixmap(SkImageInfo::Make(image->width(), image->height(), kN32_SkColorType,
300            image->alphaType()), (const void*) &pixels.front(), image->width() * 4);
301    image->readPixels(pixmap, 0, 0);
302    SkPixmap inset;
303    if (pixmap.extractSubset(&inset, {128, 128, 512, 512})) {
304        const SkImageInfo& info = inset.info();
305        const char* alphas[] = {"Unknown", "Opaque", "Premul", "Unpremul"};
306        const char* colors[] = {"Unknown", "Alpha_8", "RGB_565", "ARGB_4444", "RGBA_8888",
307                "RGB_888x", "BGRA_8888", "RGBA_1010102", "RGB_101010x", "Gray_8", "RGBA_F16"};
308        SkDebugf("width: %d height: %d color: %s alpha: %s\n", info.width(), info.height(),
309                 colors[info.colorType()], alphas[info.alphaType()]);
310    }
311#StdOut
312width: 384 height: 384 color: BGRA_8888 alpha: Opaque
313##
314##
315
316#SeeAlso Image_Info
317
318##
319
320# ------------------------------------------------------------------------------
321
322#Method size_t rowBytes() const
323
324#In Image_Info_Access
325#Line # returns interval between rows in bytes ##
326Returns row bytes, the interval from one pixel row to the next. Row bytes
327is at least as large as:
328#Formula
329width() * info().bytesPerPixel()
330##
331.
332
333Returns zero if colorType is kUnknown_SkColorType.
334It is up to the Bitmap creator to ensure that row bytes is a useful value.
335
336#Return  byte length of pixel row ##
337
338#Example
339SkPixmap badPixmap = {SkImageInfo::MakeA8(4, 4), nullptr, 2};
340SkPixmap okPixmap = {SkImageInfo::MakeA8(4, 4), nullptr, 8};
341for (auto& pixmap : { badPixmap, okPixmap } ) {
342    SkDebugf("rowBytes: %d minRowBytes: %d\n", pixmap.rowBytes(),
343       pixmap.info().minRowBytes());
344}
345#StdOut
346rowBytes: 2 minRowBytes: 4
347rowBytes: 8 minRowBytes: 4
348##
349##
350
351#SeeAlso addr() info() SkImageInfo::minRowBytes
352
353##
354
355# ------------------------------------------------------------------------------
356
357#Method const void* addr() const
358
359#In Image_Info_Access
360#Line # returns readable pixel address as void pointer ##
361Returns pixel address, the base address corresponding to the pixel origin.
362
363It is up to the Pixmap creator to ensure that pixel address is a useful value.
364
365#Return  pixel address ##
366
367#Example
368#Image 3
369    std::vector<int32_t> pixels;
370    pixels.resize(image->height() * image->width() * 4);
371    SkPixmap pixmap(SkImageInfo::Make(image->width(), image->height(), kN32_SkColorType,
372            image->alphaType()), (const void*) &pixels.front(), image->width() * 4);
373    image->readPixels(pixmap, 0, 0);
374    SkDebugf("pixels address: 0x%llx\n", pixmap.addr());
375    SkPixmap inset;
376    if (pixmap.extractSubset(&inset, {128, 128, 512, 512})) {
377         SkDebugf("inset address:  0x%llx\n", inset.addr());
378    }
379#StdOut
380#Volatile
381pixels address: 0x7f2a440bb010
382inset address:  0x7f2a440fb210
383##
384##
385
386#SeeAlso addr(int x, int y) addr8 addr16 addr32 addr64 info() rowBytes()
387
388##
389
390# ------------------------------------------------------------------------------
391
392#Method int width() const
393
394#In Image_Info_Access
395#Line # returns pixel column count ##
396Returns pixel count in each pixel row. Should be equal or less than:
397
398#Formula
399rowBytes() / info().bytesPerPixel()
400##
401.
402
403#Return  pixel width in Image_Info ##
404
405#Example
406    SkImageInfo info = SkImageInfo::MakeA8(16, 32);
407    SkPixmap pixmap(info, nullptr, 64);
408    SkDebugf("pixmap width: %d  info width: %d\n", pixmap.width(), info.width());
409#StdOut
410pixmap width: 16  info width: 16
411##
412##
413
414#SeeAlso height() SkImageInfo::width()
415
416##
417
418# ------------------------------------------------------------------------------
419
420#Method int height() const
421
422#In Image_Info_Access
423#Line # returns pixel row count ##
424Returns pixel row count.
425
426#Return  pixel height in Image_Info ##
427
428#Example
429    SkPixmap pixmap(SkImageInfo::MakeA8(16, 32), nullptr, 64);
430    SkDebugf("pixmap height: %d  info height: %d\n", pixmap.height(), pixmap.info().height());
431#StdOut
432pixmap height: 32  info height: 32
433##
434##
435
436#SeeAlso width() ImageInfo::height()
437
438##
439
440# ------------------------------------------------------------------------------
441
442#Method SkColorType colorType() const
443
444#In Image_Info_Access
445#Line # returns Image_Info Color_Type ##
446Returns Color_Type, one of: kUnknown_SkColorType, kAlpha_8_SkColorType,
447kRGB_565_SkColorType, kARGB_4444_SkColorType, kRGBA_8888_SkColorType,
448kRGB_888x_SkColorType, kBGRA_8888_SkColorType, kRGBA_1010102_SkColorType,
449kRGB_101010x_SkColorType, kGray_8_SkColorType, kRGBA_F16_SkColorType.
450
451#Return  Color_Type in Image_Info ##
452
453#Example
454    const char* colors[] = {"Unknown", "Alpha_8", "RGB_565", "ARGB_4444", "RGBA_8888", "RGB_888x",
455                            "BGRA_8888", "RGBA_1010102", "RGB_101010x", "Gray_8", "RGBA_F16"};
456    SkPixmap pixmap(SkImageInfo::MakeA8(16, 32), nullptr, 64);
457    SkDebugf("color type: k" "%s" "_SkColorType\n", colors[pixmap.colorType()]);
458#StdOut
459color type: kAlpha_8_SkColorType
460##
461##
462
463#SeeAlso alphaType() SkImageInfo::colorType
464
465##
466
467# ------------------------------------------------------------------------------
468
469#Method SkAlphaType alphaType() const
470
471#In Image_Info_Access
472#Line # returns Image_Info Alpha_Type ##
473Returns Alpha_Type, one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType,
474kPremul_SkAlphaType, kUnpremul_SkAlphaType.
475
476#Return  Alpha_Type in Image_Info ##
477
478#Example
479    const char* alphas[] = {"Unknown", "Opaque", "Premul", "Unpremul"};
480    SkPixmap pixmap(SkImageInfo::MakeA8(16, 32), nullptr, 64);
481    SkDebugf("alpha type: k" "%s" "_SkAlphaType\n", alphas[pixmap.alphaType()]);
482#StdOut
483alpha type: kPremul_SkAlphaType
484##
485##
486
487#SeeAlso colorType() SkImageInfo::alphaType
488
489##
490
491# ------------------------------------------------------------------------------
492
493#Method SkColorSpace* colorSpace() const
494
495#In Image_Info_Access
496#Line # returns Image_Info Color_Space ##
497Returns Color_Space associated with Image_Info. The
498reference count of Color_Space is unchanged. The returned Color_Space is
499immutable.
500
501#Return Color_Space, the range of colors, in Image_Info ##
502
503#Example
504#Description
505SkColorSpace::MakeSRGBLinear creates Color_Space with linear gamma
506and an sRGB gamut. This Color_Space gamma is not close to sRGB gamma.
507##
508    SkPixmap pixmap(SkImageInfo::MakeN32(16, 32, kPremul_SkAlphaType,
509            SkColorSpace::MakeSRGBLinear()), nullptr, 64);
510    SkColorSpace* colorSpace = pixmap.colorSpace();
511    SkDebugf("gammaCloseToSRGB: %s  gammaIsLinear: %s  isSRGB: %s\n",
512            colorSpace->gammaCloseToSRGB() ? "true" : "false",
513            colorSpace->gammaIsLinear() ? "true" : "false",
514            colorSpace->isSRGB() ? "true" : "false");
515#StdOut
516gammaCloseToSRGB: false  gammaIsLinear: true  isSRGB: false
517##
518##
519
520#SeeAlso Color_Space SkImageInfo::colorSpace
521
522##
523
524# ------------------------------------------------------------------------------
525
526#Method bool isOpaque() const
527
528#In Image_Info_Access
529#Line # returns true if Image_Info describes opaque pixels ##
530Returns true if Alpha_Type is kOpaque_SkAlphaType.
531Does not check if Color_Type allows Alpha, or if any pixel value has
532transparency.
533
534#Return true if Image_Info has opaque Alpha_Type ##
535
536#Example
537#Description
538    isOpaque ignores whether all pixels are opaque or not.
539##
540    std::vector<uint32_t> pixels;
541    const int height = 2;
542    const int width = 2;
543    pixels.resize(height * width * 4);
544    SkPixmap pixmap(SkImageInfo::Make(width, height, kN32_SkColorType,
545            kPremul_SkAlphaType), (const void*) &pixels.front(), width * 4);
546    for (int index = 0; index < 2; ++index) {
547        pixmap.erase(0x00000000);
548        SkDebugf("isOpaque: %s\n", pixmap.isOpaque() ? "true" : "false");
549        pixmap.erase(0xFFFFFFFF);
550        SkDebugf("isOpaque: %s\n", pixmap.isOpaque() ? "true" : "false");
551        pixmap.reset(pixmap.info().makeAlphaType(kOpaque_SkAlphaType),
552                     (const void*) &pixels.front(), width * 4);
553    }
554#StdOut
555isOpaque: false
556isOpaque: false
557isOpaque: true
558isOpaque: true
559##
560##
561
562#SeeAlso computeIsOpaque SkImageInfo::isOpaque
563
564##
565
566# ------------------------------------------------------------------------------
567
568#Method SkIRect bounds() const
569
570#In Image_Info_Access
571#Line # returns width and height as Rectangle ##
572Returns IRect { 0, 0, width(), height() }.
573
574#Return  integral rectangle from origin to width() and height() ##
575
576#Example
577    for (int width : { 0, 2 } ) {
578        for (int height : { 0, 2 } ) {
579             SkPixmap pixmap(SkImageInfo::MakeA8(width, height), nullptr, width);
580             SkDebugf("width: %d height: %d empty: %s\n", width, height,
581                      pixmap.bounds().isEmpty() ? "true" : "false");
582        }
583    }
584#StdOut
585width: 0 height: 0 empty: true
586width: 0 height: 2 empty: true
587width: 2 height: 0 empty: true
588width: 2 height: 2 empty: false
589##
590##
591
592#SeeAlso height() width() IRect
593
594##
595
596# ------------------------------------------------------------------------------
597
598#Method int rowBytesAsPixels() const
599
600#In Image_Info_Access
601#Line # returns interval between rows in pixels ##
602
603Returns number of pixels that fit on row. Should be greater than or equal to
604width().
605
606#Return  maximum pixels per row ##
607
608#Example
609    for (int rowBytes : { 4, 5, 6, 7, 8} ) {
610        SkPixmap pixmap(SkImageInfo::MakeN32(1, 1, kPremul_SkAlphaType), nullptr, rowBytes);
611        SkDebugf("rowBytes: %d rowBytesAsPixels: %d\n", rowBytes, pixmap.rowBytesAsPixels());
612    }
613#StdOut
614rowBytes: 4 rowBytesAsPixels: 1
615rowBytes: 5 rowBytesAsPixels: 1
616rowBytes: 6 rowBytesAsPixels: 1
617rowBytes: 7 rowBytesAsPixels: 1
618rowBytes: 8 rowBytesAsPixels: 2
619##
620##
621
622#SeeAlso rowBytes shiftPerPixel width SkImageInfo::bytesPerPixel
623
624##
625
626# ------------------------------------------------------------------------------
627
628#Method int shiftPerPixel() const
629
630#In Image_Info_Access
631#Line # returns bit shift from pixels to bytes ##
632Returns bit shift converting row bytes to row pixels.
633Returns zero for kUnknown_SkColorType.
634
635#Return one of: 0, 1, 2, 3; left shift to convert pixels to bytes ##
636
637#Example
638    const char* colors[] = {"Unknown", "Alpha_8", "RGB_565", "ARGB_4444", "RGBA_8888", "RGB_888x",
639                            "BGRA_8888", "RGBA_1010102", "RGB_101010x", "Gray_8", "RGBA_F16"};
640    SkImageInfo info = SkImageInfo::MakeA8(1, 1);
641    for (SkColorType colorType : { kUnknown_SkColorType,   kAlpha_8_SkColorType,
642                                   kRGB_565_SkColorType,   kARGB_4444_SkColorType,
643                                   kRGBA_8888_SkColorType, kBGRA_8888_SkColorType,
644                                   kGray_8_SkColorType,    kRGBA_F16_SkColorType } ) {
645        SkPixmap pixmap(info.makeColorType(colorType), nullptr, 4);
646        SkDebugf("color: k" "%s" "_SkColorType" "%*s" "bytesPerPixel: %d shiftPerPixel: %d\n",
647                colors[colorType], 10 - strlen(colors[colorType]), " ",
648                pixmap.info().bytesPerPixel(), pixmap.shiftPerPixel());
649    }
650#StdOut
651color: kUnknown_SkColorType   bytesPerPixel: 0 shiftPerPixel: 0
652color: kAlpha_8_SkColorType   bytesPerPixel: 1 shiftPerPixel: 0
653color: kRGB_565_SkColorType   bytesPerPixel: 2 shiftPerPixel: 1
654color: kARGB_4444_SkColorType bytesPerPixel: 2 shiftPerPixel: 1
655color: kRGBA_8888_SkColorType bytesPerPixel: 4 shiftPerPixel: 2
656color: kBGRA_8888_SkColorType bytesPerPixel: 4 shiftPerPixel: 2
657color: kGray_8_SkColorType    bytesPerPixel: 1 shiftPerPixel: 0
658color: kRGBA_F16_SkColorType  bytesPerPixel: 8 shiftPerPixel: 3
659##
660##
661
662#SeeAlso rowBytes rowBytesAsPixels width SkImageInfo::bytesPerPixel
663
664##
665
666# ------------------------------------------------------------------------------
667
668#Method size_t computeByteSize() const
669
670#In Image_Info_Access
671#Line # returns size required for pixels ##
672Returns minimum memory required for pixel storage.
673Does not include unused memory on last row when rowBytesAsPixels exceeds width().
674Returns zero if result does not fit in size_t.
675Returns zero if height() or width() is 0.
676Returns height() times rowBytes if colorType is kUnknown_SkColorType.
677
678#Return size in bytes of image buffer ##
679
680#Example
681    SkPixmap pixmap;
682    for (int width : { 1, 1000, 1000000 } ) {
683        for (int height: { 1, 1000, 1000000 } ) {
684            SkImageInfo imageInfo = SkImageInfo::MakeN32(width, height, kPremul_SkAlphaType);
685            pixmap.reset(imageInfo, nullptr, width * 5);
686            SkDebugf("width: %7d height: %7d computeByteSize: %13lld\n", width, height,
687                     pixmap.computeByteSize());
688        }
689    }
690#StdOut
691width:       1 height:       1 computeByteSize:             4
692width:       1 height:    1000 computeByteSize:          4999
693width:       1 height: 1000000 computeByteSize:       4999999
694width:    1000 height:       1 computeByteSize:          4000
695width:    1000 height:    1000 computeByteSize:       4999000
696width:    1000 height: 1000000 computeByteSize:    4999999000
697width: 1000000 height:       1 computeByteSize:       4000000
698width: 1000000 height:    1000 computeByteSize:    4999000000
699width: 1000000 height: 1000000 computeByteSize: 4999999000000
700##
701##
702
703#SeeAlso SkImageInfo::computeByteSize
704
705##
706
707#Subtopic Image_Info_Access ##
708
709#Subtopic Reader
710#Line # examine pixel value ##
711
712# ------------------------------------------------------------------------------
713
714#Method bool computeIsOpaque() const
715
716#In Reader
717#Line # returns true if all pixels are opaque ##
718Returns true if all pixels are opaque. Color_Type determines how pixels
719are encoded, and whether pixel describes Alpha. Returns true for Color_Types
720without alpha in each pixel; for other Color_Types, returns true if all
721pixels have alpha values equivalent to 1.0 or greater.
722
723For Color_Types kRGB_565_SkColorType or kGray_8_SkColorType: always
724returns true. For Color_Types kAlpha_8_SkColorType, kBGRA_8888_SkColorType,
725kRGBA_8888_SkColorType: returns true if all pixel Alpha values are 255.
726For Color_Type kARGB_4444_SkColorType: returns true if all pixel Alpha values are 15.
727For kRGBA_F16_SkColorType: returns true if all pixel Alpha values are 1.0 or
728greater.
729
730Returns false for kUnknown_SkColorType.
731
732#Return true if all pixels have opaque values or Color_Type is opaque  ##
733
734#Example
735    std::vector<uint32_t> pixels;
736    const int height = 2;
737    const int width = 2;
738    pixels.resize(height * width * 4);
739    SkPixmap pixmap(SkImageInfo::Make(width, height, kN32_SkColorType,
740            kPremul_SkAlphaType), (const void*) &pixels.front(), width * 4);
741    for (int index = 0; index < 2; ++index) {
742        pixmap.erase(0x00000000);
743        SkDebugf("computeIsOpaque: %s\n", pixmap.computeIsOpaque() ? "true" : "false");
744        pixmap.erase(0xFFFFFFFF);
745        SkDebugf("computeIsOpaque: %s\n", pixmap.computeIsOpaque() ? "true" : "false");
746        pixmap.reset(pixmap.info().makeAlphaType(kOpaque_SkAlphaType),
747                     (const void*) &pixels.front(), width * 4);
748    }
749#StdOut
750computeIsOpaque: false
751computeIsOpaque: true
752computeIsOpaque: false
753computeIsOpaque: true
754##
755##
756
757#SeeAlso isOpaque Color_Type Alpha
758
759##
760
761# ------------------------------------------------------------------------------
762
763#Method SkColor getColor(int x, int y) const
764
765#In Reader
766#Line # returns one pixel as Unpremultiplied Color ##
767Returns pixel at (x, y) as Unpremultiplied Color.
768Returns black with Alpha if Color_Type is kAlpha_8_SkColorType.
769
770Input is not validated: out of bounds values of x or y trigger an assert() if
771built with SK_DEBUG defined; and returns undefined values or may crash if
772SK_RELEASE is defined. Fails if Color_Type is kUnknown_SkColorType or
773pixel address is nullptr.
774
775Color_Space in Image_Info is ignored. Some Color precision may be lost in the
776conversion to Unpremultiplied Color; original pixel data may have additional
777precision.
778
779#Param x  column index, zero or greater, and less than width() ##
780#Param y  row index, zero or greater, and less than height() ##
781
782#Return  pixel converted to Unpremultiplied Color ##
783
784#Example
785    const int w = 4;
786    const int h = 4;
787    std::vector<SkPMColor> storage;
788    storage.resize(w * h);
789    SkDebugf("Premultiplied:\n");
790    for (int y = 0; y < h; ++y) {
791        SkDebugf("(0, %d) ", y);
792        for (int x = 0; x < w; ++x) {
793            int a = 0xFF * (x + y) / (w - 1 + h - 1);
794            storage[x + y * w] = SkPackARGB32(a, a * x / (w - 1), a * y / (h - 1), a);
795            SkDebugf("0x%08x%c", storage[x + y * w], x == w - 1 ? '\n' : ' ');
796        }
797    }
798    SkPixmap pixmap(SkImageInfo::MakeN32(w, h, kPremul_SkAlphaType), &storage.front(), w * 4);
799    SkDebugf("Unpremultiplied:\n");
800    for (int y = 0; y < h; ++y) {
801        SkDebugf("(0, %d) ", y);
802        for (int x = 0; x < w; ++x) {
803            SkDebugf("0x%08x%c", pixmap.getColor(x, y), x == w - 1 ? '\n' : ' ');
804        }
805    }
806#StdOut
807Premultiplied:
808(0, 0) 0x00000000 0x2a0e002a 0x55380055 0x7f7f007f
809(0, 1) 0x2a000e2a 0x551c1c55 0x7f542a7f 0xaaaa38aa
810(0, 2) 0x55003855 0x7f2a547f 0xaa7171aa 0xd4d48dd4
811(0, 3) 0x7f007f7f 0xaa38aaaa 0xd48dd4d4 0xffffffff
812Unpremultiplied:
813(0, 0) 0x00000000 0x2a5500ff 0x55a800ff 0x7fff00ff
814(0, 1) 0x2a0055ff 0x555454ff 0x7fa954ff 0xaaff54ff
815(0, 2) 0x5500a8ff 0x7f54a9ff 0xaaaaaaff 0xd4ffaaff
816(0, 3) 0x7f00ffff 0xaa54ffff 0xd4aaffff 0xffffffff
817##
818##
819
820#SeeAlso addr() readPixels
821
822##
823
824#Subtopic Reader ##
825
826#Subtopic Readable_Address
827#Line # returns read only pixels ##
828
829# ------------------------------------------------------------------------------
830
831#Method const void* addr(int x, int y) const
832
833#In Readable_Address
834Returns readable pixel address at (x, y). Returns nullptr if Pixel_Ref is nullptr.
835
836Input is not validated: out of bounds values of x or y trigger an assert() if
837built with SK_DEBUG defined. Returns nullptr if Color_Type is kUnknown_SkColorType.
838
839Performs a lookup of pixel size; for better performance, call
840one of: addr8, addr16, addr32, addr64, or addrF16.
841
842#Param x  column index, zero or greater, and less than width() ##
843#Param y  row index, zero or greater, and less than height() ##
844
845#Return  readable generic pointer to pixel ##
846
847#Example
848    const int w = 4;
849    const int h = 4;
850    std::vector<SkPMColor> storage;
851    storage.resize(w * h);
852    SkPixmap pixmap(SkImageInfo::MakeN32(w, h, kPremul_SkAlphaType), &storage.front(), w * 4);
853    SkDebugf("pixmap.addr(1, 2) %c= &storage[1 + 2 * w]\n",
854              pixmap.addr(1, 2)  == &storage[1 + 2 * w] ? '=' : '!');
855#StdOut
856pixmap.addr(1, 2) == &storage[1 + 2 * w]
857##
858##
859
860#SeeAlso addr8 addr16 addr32 addr64 addrF16 getColor writable_addr SkBitmap::getAddr
861
862##
863
864# ------------------------------------------------------------------------------
865
866#Method const uint8_t* addr8() const
867
868#In Readable_Address
869#Line # returns readable pixel address as 8-bit pointer ##
870Returns readable base pixel address. Result is addressable as unsigned 8-bit bytes.
871Will trigger an assert() if Color_Type is not kAlpha_8_SkColorType or
872kGray_8_SkColorType, and is built with SK_DEBUG defined.
873
874One byte corresponds to one pixel.
875
876#Return  readable unsigned 8-bit pointer to pixels ##
877
878#Example
879    const int w = 4;
880    const int h = 4;
881    uint8_t storage[w * h];
882    SkPixmap pixmap(SkImageInfo::Make(w, h, kGray_8_SkColorType, kPremul_SkAlphaType),
883                    storage, w * sizeof(storage[0]));
884    SkDebugf("pixmap.addr8() %c= storage\n",
885              pixmap.addr8()  == storage ? '=' : '!');
886#StdOut
887pixmap.addr8() == storage
888##
889##
890
891#SeeAlso addr() addr16 addr32 addr64 addrF16 getColor writable_addr writable_addr8
892
893##
894
895# ------------------------------------------------------------------------------
896
897#Method const uint16_t* addr16() const
898
899#In Readable_Address
900#Line # returns readable pixel address as 16-bit pointer ##
901Returns readable base pixel address. Result is addressable as unsigned 16-bit words.
902Will trigger an assert() if Color_Type is not kRGB_565_SkColorType or
903kARGB_4444_SkColorType, and is built with SK_DEBUG defined.
904
905One word corresponds to one pixel.
906
907#Return  readable unsigned 16-bit pointer to pixels ##
908
909#Example
910    const int w = 4;
911    const int h = 4;
912    uint16_t storage[w * h];
913    SkPixmap pixmap(SkImageInfo::Make(w, h, kARGB_4444_SkColorType, kPremul_SkAlphaType),
914                    storage, w * sizeof(storage[0]));
915    SkDebugf("pixmap.addr16() %c= storage\n",
916              pixmap.addr16()  == storage ? '=' : '!');
917#StdOut
918pixmap.addr16() == storage
919##
920##
921
922#SeeAlso addr() addr8 addr32 addr64 addrF16 getColor writable_addr writable_addr16
923
924##
925
926# ------------------------------------------------------------------------------
927
928#Method const uint32_t* addr32() const
929
930#In Readable_Address
931#Line # returns readable pixel address as 32-bit pointer ##
932Returns readable base pixel address. Result is addressable as unsigned 32-bit words.
933Will trigger an assert() if Color_Type is not kRGBA_8888_SkColorType or
934kBGRA_8888_SkColorType, and is built with SK_DEBUG defined.
935
936One word corresponds to one pixel.
937
938#Return  readable unsigned 32-bit pointer to pixels ##
939
940#Example
941    const int w = 4;
942    const int h = 4;
943    uint32_t storage[w * h];
944    SkPixmap pixmap(SkImageInfo::MakeN32(w, h, kPremul_SkAlphaType),
945                    storage, w * sizeof(storage[0]));
946    SkDebugf("pixmap.addr32() %c= storage\n",
947              pixmap.addr32()  == storage ? '=' : '!');
948#StdOut
949pixmap.addr32() == storage
950##
951##
952
953#SeeAlso addr() addr8 addr16 addr64 addrF16 getColor writable_addr writable_addr32
954
955##
956
957# ------------------------------------------------------------------------------
958
959#Method const uint64_t* addr64() const
960
961#In Readable_Address
962#Line # returns readable pixel address as 64-bit pointer ##
963Returns readable base pixel address. Result is addressable as unsigned 64-bit words.
964Will trigger an assert() if Color_Type is not kRGBA_F16_SkColorType and is built
965with SK_DEBUG defined.
966
967One word corresponds to one pixel.
968
969#Return  readable unsigned 64-bit pointer to pixels ##
970
971#Example
972    const int w = 4;
973    const int h = 4;
974    uint64_t storage[w * h];
975    SkPixmap pixmap(SkImageInfo::Make(w, h, kRGBA_F16_SkColorType, kPremul_SkAlphaType),
976                    storage, w * sizeof(storage[0]));
977    SkDebugf("pixmap.addr64() %c= storage\n",
978              pixmap.addr64()  == storage ? '=' : '!');
979#StdOut
980pixmap.addr64() == storage
981##
982##
983
984#SeeAlso addr() addr8 addr16 addr32 addrF16 getColor writable_addr writable_addr64
985
986##
987
988# ------------------------------------------------------------------------------
989
990#Method const uint16_t* addrF16() const
991
992#In Readable_Address
993#Line # returns readable pixel component address as 16-bit pointer ##
994Returns readable base pixel address. Result is addressable as unsigned 16-bit words.
995Will trigger an assert() if Color_Type is not kRGBA_F16_SkColorType and is built
996with SK_DEBUG defined.
997
998Each word represents one color component encoded as a half float.
999Four words correspond to one pixel.
1000
1001#Return  readable unsigned 16-bit pointer to first component of pixels ##
1002
1003#Example
1004    const int w = 4;
1005    const int h = 4;
1006    uint16_t storage[w * h * 4];
1007    SkPixmap pixmap(SkImageInfo::Make(w, h, kRGBA_F16_SkColorType, kPremul_SkAlphaType),
1008                    storage, w * 4 * sizeof(storage[0]));
1009    SkDebugf("pixmap.addrF16() %c= storage\n",
1010              pixmap.addrF16()  == storage ? '=' : '!');
1011#StdOut
1012pixmap.addrF16() == storage
1013##
1014##
1015
1016#SeeAlso addr() addr8 addr16 addr32 addr64 getColor writable_addr writable_addrF16
1017
1018##
1019
1020# ------------------------------------------------------------------------------
1021
1022#Method const uint8_t* addr8(int x, int y) const
1023
1024#In Readable_Address
1025Returns readable pixel address at (x, y).
1026
1027Input is not validated: out of bounds values of x or y trigger an assert() if
1028built with SK_DEBUG defined.
1029
1030Will trigger an assert() if Color_Type is not kAlpha_8_SkColorType or
1031kGray_8_SkColorType, and is built with SK_DEBUG defined.
1032
1033#Param x  column index, zero or greater, and less than width() ##
1034#Param y  row index, zero or greater, and less than height() ##
1035
1036#Return  readable unsigned 8-bit pointer to pixel at (x, y) ##
1037
1038#Example
1039    const int w = 4;
1040    const int h = 4;
1041    uint8_t storage[w * h];
1042    SkPixmap pixmap(SkImageInfo::Make(w, h, kGray_8_SkColorType, kPremul_SkAlphaType),
1043                    storage, w * sizeof(storage[0]));
1044    SkDebugf("pixmap.addr8(1, 2) %c= &storage[1 + 2 * w]\n",
1045              pixmap.addr8(1, 2)  == &storage[1 + 2 * w] ? '=' : '!');
1046#StdOut
1047pixmap.addr8(1, 2) == &storage[1 + 2 * w]
1048##
1049##
1050
1051#SeeAlso addr() addr16 addr32 addr64 addrF16 getColor writable_addr writable_addr8
1052
1053##
1054
1055# ------------------------------------------------------------------------------
1056
1057#Method const uint16_t* addr16(int x, int y) const
1058
1059#In Readable_Address
1060Returns readable pixel address at (x, y).
1061
1062Input is not validated: out of bounds values of x or y trigger an assert() if
1063built with SK_DEBUG defined.
1064
1065Will trigger an assert() if Color_Type is not kRGB_565_SkColorType or
1066kARGB_4444_SkColorType, and is built with SK_DEBUG defined.
1067
1068#Param x  column index, zero or greater, and less than width() ##
1069#Param y  row index, zero or greater, and less than height() ##
1070
1071#Return  readable unsigned 16-bit pointer to pixel at (x, y) ##
1072
1073#Example
1074    const int w = 4;
1075    const int h = 4;
1076    uint16_t storage[w * h];
1077    SkPixmap pixmap(SkImageInfo::Make(w, h, kARGB_4444_SkColorType, kPremul_SkAlphaType),
1078                    storage, w * sizeof(storage[0]));
1079    SkDebugf("pixmap.addr16(1, 2) %c= &storage[1 + 2 * w]\n",
1080              pixmap.addr16(1, 2)  == &storage[1 + 2 * w] ? '=' : '!');
1081#StdOut
1082pixmap.addr16(1, 2) == &storage[1 + 2 * w]
1083##
1084##
1085
1086#SeeAlso addr() addr8 addr32 addr64 addrF16 getColor writable_addr writable_addr16
1087
1088##
1089
1090# ------------------------------------------------------------------------------
1091
1092#Method const uint32_t* addr32(int x, int y) const
1093
1094#In Readable_Address
1095Returns readable pixel address at (x, y).
1096
1097Input is not validated: out of bounds values of x or y trigger an assert() if
1098built with SK_DEBUG defined.
1099
1100Will trigger an assert() if Color_Type is not kRGBA_8888_SkColorType or
1101kBGRA_8888_SkColorType, and is built with SK_DEBUG defined.
1102
1103#Param x  column index, zero or greater, and less than width() ##
1104#Param y  row index, zero or greater, and less than height() ##
1105
1106#Return  readable unsigned 32-bit pointer to pixel at (x, y) ##
1107
1108#Example
1109    const int w = 4;
1110    const int h = 4;
1111    uint32_t storage[w * h];
1112    SkPixmap pixmap(SkImageInfo::Make(w, h, kRGBA_8888_SkColorType, kPremul_SkAlphaType),
1113                    storage, w * sizeof(storage[0]));
1114    SkDebugf("pixmap.addr32(1, 2) %c= &storage[1 + 2 * w]\n",
1115              pixmap.addr32(1, 2)  == &storage[1 + 2 * w] ? '=' : '!');
1116#StdOut
1117pixmap.addr32(1, 2) == &storage[1 + 2 * w]
1118##
1119##
1120
1121#SeeAlso addr() addr8 addr16 addr64 addrF16 getColor writable_addr writable_addr64
1122
1123##
1124
1125# ------------------------------------------------------------------------------
1126
1127#Method const uint64_t* addr64(int x, int y) const
1128
1129#In Readable_Address
1130Returns readable pixel address at (x, y).
1131
1132Input is not validated: out of bounds values of x or y trigger an assert() if
1133built with SK_DEBUG defined.
1134
1135Will trigger an assert() if Color_Type is not kRGBA_F16_SkColorType and is built
1136with SK_DEBUG defined.
1137
1138#Param x  column index, zero or greater, and less than width() ##
1139#Param y  row index, zero or greater, and less than height() ##
1140
1141#Return  readable unsigned 64-bit pointer to pixel at (x, y) ##
1142
1143#Example
1144    const int w = 4;
1145    const int h = 4;
1146    uint64_t storage[w * h];
1147    SkPixmap pixmap(SkImageInfo::Make(w, h, kRGBA_F16_SkColorType, kPremul_SkAlphaType),
1148                    storage, w * sizeof(storage[0]));
1149    SkDebugf("pixmap.addr64(1, 2) %c= &storage[1 + 2 * w]\n",
1150              pixmap.addr64(1, 2)  == &storage[1 + 2 * w] ? '=' : '!');
1151#StdOut
1152pixmap.addr64(1, 2) == &storage[1 + 2 * w]
1153##
1154##
1155
1156#SeeAlso addr() addr8 addr16 addr32 addrF16 getColor writable_addr writable_addr64
1157
1158##
1159
1160# ------------------------------------------------------------------------------
1161
1162#Method const uint16_t* addrF16(int x, int y) const
1163
1164#In Readable_Address
1165Returns readable pixel address at (x, y).
1166
1167Input is not validated: out of bounds values of x or y trigger an assert() if
1168built with SK_DEBUG defined.
1169
1170Will trigger an assert() if Color_Type is not kRGBA_F16_SkColorType and is built
1171with SK_DEBUG defined.
1172
1173Each unsigned 16-bit word represents one color component encoded as a half float.
1174Four words correspond to one pixel.
1175
1176#Param x  column index, zero or greater, and less than width() ##
1177#Param y  row index, zero or greater, and less than height() ##
1178
1179#Return  readable unsigned 16-bit pointer to pixel component at (x, y) ##
1180
1181#Example
1182    const int w = 4;
1183    const int h = 4;
1184    const int wordsPerPixel = 4;
1185    const int rowWords = w * wordsPerPixel;
1186    uint16_t storage[rowWords * h];
1187    SkPixmap pixmap(SkImageInfo::Make(w, h, kRGBA_F16_SkColorType, kPremul_SkAlphaType),
1188                    storage, rowWords * sizeof(storage[0]));
1189    SkDebugf("pixmap.addrF16(1, 2) %c= &storage[1 * wordsPerPixel + 2 * rowWords]\n",
1190              pixmap.addrF16(1, 2)  == &storage[1 * wordsPerPixel + 2 * rowWords] ? '=' : '!');
1191#StdOut
1192pixmap.addrF16(1, 2) == &storage[1 * wordsPerPixel + 2 * rowWords]
1193##
1194##
1195
1196#SeeAlso addr() addr8 addr16 addr32 addr64 getColor writable_addr writable_addrF16
1197
1198##
1199
1200#Subtopic Readable_Address ##
1201
1202#Subtopic Writable_Address
1203#Line # returns writable pixels ##
1204
1205# ------------------------------------------------------------------------------
1206
1207#Method void* writable_addr() const
1208
1209#In Writable_Address
1210#Line # returns writable pixel address as void pointer ##
1211Returns writable base pixel address.
1212
1213#Return  writable generic base pointer to pixels ##
1214
1215#Example
1216    const int w = 4;
1217    const int h = 4;
1218    SkPMColor storage[w * h * 4];
1219    SkPixmap pixmap(SkImageInfo::MakeN32(w, h, kPremul_SkAlphaType), storage, w * 4);
1220    SkDebugf("pixmap.writable_addr() %c= (void *)storage\n",
1221              pixmap.writable_addr()  == (void *)storage ? '=' : '!');
1222    pixmap.erase(0x00000000);
1223    *(SkPMColor*)pixmap.writable_addr() = 0xFFFFFFFF;
1224    SkDebugf("pixmap.getColor(0, 1) %c= 0x00000000\n",
1225              pixmap.getColor(0, 1)  == 0x00000000 ? '=' : '!');
1226    SkDebugf("pixmap.getColor(0, 0) %c= 0xFFFFFFFF\n",
1227              pixmap.getColor(0, 0)  == 0xFFFFFFFF ? '=' : '!');
1228#StdOut
1229pixmap.writable_addr() == (void *)storage
1230pixmap.getColor(0, 1) == 0x00000000
1231pixmap.getColor(0, 0) == 0xFFFFFFFF
1232##
1233##
1234
1235#SeeAlso writable_addr8 writable_addr16 writable_addr32 writable_addr64 writable_addrF16 addr()
1236
1237##
1238
1239# ------------------------------------------------------------------------------
1240
1241#Method void* writable_addr(int x, int y) const
1242
1243#In Writable_Address
1244Returns writable pixel address at (x, y).
1245
1246Input is not validated: out of bounds values of x or y trigger an assert() if
1247built with SK_DEBUG defined. Returns zero if Color_Type is kUnknown_SkColorType.
1248
1249#Param x  column index, zero or greater, and less than width() ##
1250#Param y  row index, zero or greater, and less than height() ##
1251
1252#Return  writable generic pointer to pixel ##
1253
1254#Example
1255    const int w = 4;
1256    const int h = 4;
1257    SkPMColor storage[w * h * 4];
1258    SkPixmap pixmap(SkImageInfo::MakeN32(w, h, kPremul_SkAlphaType), storage, w * 4);
1259    SkDebugf("pixmap.writable_addr() %c= (void *)storage\n",
1260              pixmap.writable_addr()  == (void *)storage ? '=' : '!');
1261    pixmap.erase(0x00000000);
1262    *(SkPMColor*)pixmap.writable_addr(1, 2) = 0xFFFFFFFF;
1263    SkDebugf("pixmap.getColor(0, 0) %c= 0x00000000\n",
1264              pixmap.getColor(0, 0)  == 0x00000000 ? '=' : '!');
1265    SkDebugf("pixmap.getColor(1, 2) %c= 0xFFFFFFFF\n",
1266              pixmap.getColor(1, 2)  == 0xFFFFFFFF ? '=' : '!');
1267#StdOut
1268pixmap.writable_addr() == (void *)storage
1269pixmap.getColor(0, 0) == 0x00000000
1270pixmap.getColor(1, 2) == 0xFFFFFFFF
1271##
1272##
1273
1274#SeeAlso writable_addr8 writable_addr16 writable_addr32 writable_addr64 writable_addrF16 addr()
1275
1276##
1277
1278# ------------------------------------------------------------------------------
1279
1280#Method uint8_t* writable_addr8(int x, int y) const
1281
1282#In Writable_Address
1283#Line # returns writable pixel address as 8-bit pointer ##
1284Returns writable pixel address at (x, y). Result is addressable as unsigned
12858-bit bytes. Will trigger an assert() if Color_Type is not kAlpha_8_SkColorType
1286or kGray_8_SkColorType, and is built with SK_DEBUG defined.
1287
1288One byte corresponds to one pixel.
1289
1290#Param x  column index, zero or greater, and less than width() ##
1291#Param y  row index, zero or greater, and less than height() ##
1292
1293#Return  writable unsigned 8-bit pointer to pixels ##
1294
1295#Example
1296#Height 64
1297#Description
1298Altering pixels after drawing Bitmap is not guaranteed to affect subsequent
1299drawing on all platforms. Adding a second SkBitmap::installPixels after editing
1300pixel memory is safer.
1301##
1302void draw(SkCanvas* canvas) {
1303    uint8_t storage[][5] = {{ 0,   0,  64,   0,  0},
1304                            { 0, 128, 255, 128,  0},
1305                            {64, 255, 255, 255, 64},
1306                            { 0, 128, 255, 128,  0},
1307                            { 0,   0,  64,   0,  0}};
1308    SkImageInfo imageInfo = SkImageInfo::Make(5, 5, kGray_8_SkColorType, kPremul_SkAlphaType);
1309    SkPixmap pixmap(imageInfo, storage[0], 5);
1310    SkBitmap bitmap;
1311    bitmap.installPixels(pixmap);
1312    canvas->scale(10, 10);
1313    canvas->drawBitmap(bitmap, 0, 0);
1314    *pixmap.writable_addr8(2, 2) = 0;
1315//  bitmap.installPixels(pixmap);      // uncomment to fix on GPU
1316    canvas->drawBitmap(bitmap, 10, 0);
1317}
1318##
1319
1320#SeeAlso writable_addr writable_addr16 writable_addr32 writable_addr64 writable_addrF16 addr() addr8
1321
1322##
1323
1324# ------------------------------------------------------------------------------
1325
1326#Method uint16_t* writable_addr16(int x, int y) const
1327
1328#In Writable_Address
1329#Line # returns writable pixel address as 16-bit pointer ##
1330Returns writable_addr pixel address at (x, y). Result is addressable as unsigned
133116-bit words. Will trigger an assert() if Color_Type is not kRGB_565_SkColorType
1332or kARGB_4444_SkColorType, and is built with SK_DEBUG defined.
1333
1334One word corresponds to one pixel.
1335
1336#Param x  column index, zero or greater, and less than width() ##
1337#Param y  row index, zero or greater, and less than height() ##
1338
1339#Return  writable unsigned 16-bit pointer to pixel ##
1340
1341#Example
1342#Description
1343Draw a five by five bitmap, and draw it again with a center black pixel.
1344The low nibble of the 16-bit word is Alpha.
1345##
1346#Height 64
1347    uint16_t storage[][5] = {{ 0xCABF, 0xDABE, 0xCA9D, 0xC96C, 0xA39B },
1348                             { 0xACEE, 0xA87C, 0x893A, 0x4779, 0x8708 },
1349                             { 0x4B7C, 0x255B, 0x2559, 0x2557, 0x4656 },
1350                             { 0x9099, 0x8128, 0x2557, 0x4124, 0x3323 },
1351                             { 0x7547, 0x5505, 0x4434, 0x2012, 0x0000 }};
1352    SkImageInfo imageInfo = SkImageInfo::Make(5, 5, kARGB_4444_SkColorType, kPremul_SkAlphaType);
1353    SkPixmap pixmap(imageInfo, storage[0], sizeof(storage) / 5);
1354    SkBitmap bitmap;
1355    bitmap.installPixels(pixmap);
1356    canvas->scale(10, 10);
1357    canvas->drawBitmap(bitmap, 0, 0);
1358    *pixmap.writable_addr16(2, 2) = 0x000F;
1359    bitmap.installPixels(pixmap);
1360    canvas->drawBitmap(bitmap, 10, 0);
1361##
1362
1363#SeeAlso writable_addr writable_addr8 writable_addr32 writable_addr64 writable_addrF16 addr() addr16
1364
1365##
1366
1367# ------------------------------------------------------------------------------
1368
1369#Method uint32_t* writable_addr32(int x, int y) const
1370
1371#In Writable_Address
1372#Line # returns writable pixel address as 32-bit pointer ##
1373Returns writable pixel address at (x, y). Result is addressable as unsigned
137432-bit words. Will trigger an assert() if Color_Type is not
1375kRGBA_8888_SkColorType or kBGRA_8888_SkColorType, and is built with SK_DEBUG
1376defined.
1377
1378One word corresponds to one pixel.
1379
1380#Param x  column index, zero or greater, and less than width() ##
1381#Param y  row index, zero or greater, and less than height() ##
1382
1383#Return  writable unsigned 32-bit pointer to pixel ##
1384
1385#Example
1386#Image 4
1387#Height 72
1388    std::vector<int32_t> pixels;
1389    pixels.resize(image->height() * image->width() * 4);
1390    SkPixmap pixmap(SkImageInfo::Make(image->width(), image->height(), kN32_SkColorType,
1391            image->alphaType()), (const void*) &pixels.front(), image->width() * 4);
1392    image->readPixels(pixmap, 0, 0);
1393    for (int y = 0; y < pixmap.height() / 2; ++y) {
1394        for (int x = 0; x < pixmap.width(); ++x) {
1395            if ((x & 4) == (y & 4)) {
1396                SkTSwap(*pixmap.writable_addr32(x, y),
1397                        *pixmap.writable_addr32(pixmap.width() - x, pixmap.height() - y));
1398            }
1399        }
1400    }
1401    SkBitmap bitmap;
1402    bitmap.installPixels(pixmap);
1403    canvas->drawBitmap(bitmap, 0, 0);
1404##
1405
1406#SeeAlso writable_addr writable_addr8 writable_addr16 writable_addr64 writable_addrF16 addr() addr32
1407
1408##
1409
1410# ------------------------------------------------------------------------------
1411
1412#Method uint64_t* writable_addr64(int x, int y) const
1413
1414#In Writable_Address
1415#Line # returns writable pixel address as 64-bit pointer ##
1416Returns writable pixel address at (x, y). Result is addressable as unsigned
141764-bit words. Will trigger an assert() if Color_Type is not
1418kRGBA_F16_SkColorType and is built with SK_DEBUG defined.
1419
1420One word corresponds to one pixel.
1421
1422#Param x  column index, zero or greater, and less than width() ##
1423#Param y  row index, zero or greater, and less than height() ##
1424
1425#Return  writable unsigned 64-bit pointer to pixel ##
1426
1427#Example
1428#Height 40
1429    SkImageInfo info = SkImageInfo::Make(3, 3, kRGBA_F16_SkColorType, kPremul_SkAlphaType);
1430    uint64_t storage[9];
1431    SkPixmap pixmap(info, storage, 3 * sizeof(uint64_t));
1432    SkColor4f c4 { 1, 0.45f, 0.25f, 0.65f };
1433    pixmap.erase(c4);
1434    SkBitmap bitmap;
1435    canvas->scale(10, 10);
1436    bitmap.installPixels(pixmap);
1437    canvas->drawBitmap(bitmap, 0, 0);
1438    *pixmap.writable_addr64(1, 1) |= 0x00ff000000000000LL;
1439    bitmap.installPixels(pixmap);
1440    canvas->drawBitmap(bitmap, 10, 0);
1441##
1442
1443#SeeAlso writable_addr writable_addr8 writable_addr16 writable_addr32 writable_addrF16 addr() addr64
1444
1445##
1446
1447# ------------------------------------------------------------------------------
1448
1449#Method uint16_t* writable_addrF16(int x, int y) const
1450
1451#In Writable_Address
1452#Line # returns writable pixel component address as 16-bit pointer ##
1453Returns writable pixel address at (x, y). Result is addressable as unsigned
145416-bit words. Will trigger an assert() if Color_Type is not
1455kRGBA_F16_SkColorType and is built with SK_DEBUG defined.
1456
1457Each word represents one color component encoded as a half float.
1458Four words correspond to one pixel.
1459
1460#Param x  column index, zero or greater, and less than width() ##
1461#Param y  row index, zero or greater, and less than height() ##
1462
1463#Return  writable unsigned 16-bit pointer to first component of pixel ##
1464
1465#Example
1466#Height 64
1467#Description
1468Left bitmap is drawn with two pixels defined in half float format. Right bitmap
1469is drawn after overwriting bottom half float color with top half float color.
1470##
1471    SkImageInfo info = SkImageInfo::Make(1, 2, kRGBA_F16_SkColorType, kPremul_SkAlphaType);
1472    uint16_t storage[2][4];
1473    SkPixmap pixmap(info, storage[0], sizeof(uint64_t));
1474    SkIRect topPixelBounds = {0, 0, 1, 1};
1475    pixmap.erase({ 0.65f, 0.45f, 0.25f, 1 }, &topPixelBounds);
1476    SkIRect bottomPixelBounds = {0, 1, 1, 2};
1477    pixmap.erase({ 0.25f, 0.65f, 0.45f, 1 }, &bottomPixelBounds);
1478    SkBitmap bitmap;
1479    canvas->scale(20, 20);
1480    bitmap.installPixels(pixmap);
1481    canvas->drawBitmap(bitmap, 0, 0);
1482    uint16_t* pixel2 = pixmap.writable_addrF16(0, 1);
1483    for (int i = 0; i < 4; ++i) {
1484        pixel2[i] = storage[0][i];
1485    }
1486    bitmap.installPixels(pixmap);
1487    canvas->drawBitmap(bitmap, 4, 0);
1488##
1489
1490#SeeAlso writable_addr writable_addr8 writable_addr16 writable_addr32 writable_addr64 addr() addrF16
1491
1492##
1493
1494#Subtopic Writable_Address ##
1495
1496#Subtopic Pixels
1497#Populate
1498#Line # read and write pixel values ##
1499##
1500
1501# ------------------------------------------------------------------------------
1502
1503#Method bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes,
1504                    int srcX, int srcY, SkTransferFunctionBehavior behavior) const
1505#In Pixels
1506#Line # copies and converts pixels ##
1507
1508Copies a Rect of pixels to dstPixels. Copy starts at (srcX, srcY), and does not
1509exceed Pixmap (width(), height()).
1510
1511dstInfo specifies width, height, Color_Type, Alpha_Type, and
1512Color_Space of destination. dstRowBytes specifics the gap from one destination
1513row to the next. Returns true if pixels are copied. Returns false if
1514dstInfo.addr() equals nullptr, or dstRowBytes is less than dstInfo.minRowBytes.
1515
1516Pixels are copied only if pixel conversion is possible. If Pixmap colorType is
1517kGray_8_SkColorType, or kAlpha_8_SkColorType; dstInfo.colorType must match.
1518If Pixmap colorType is kGray_8_SkColorType, dstInfo.colorSpace must match.
1519If Pixmap alphaType is kOpaque_SkAlphaType, dstInfo.alphaType must
1520match. If Pixmap colorSpace is nullptr, dstInfo.colorSpace must match. Returns
1521false if pixel conversion is not possible.
1522
1523srcX and srcY may be negative to copy only top or left of source. Returns
1524false if width() or height() is zero or negative. Returns false if:
1525
1526#Formula
1527abs(srcX) >= Pixmap width()
1528##
1529, or if
1530#Formula
1531abs(srcY) >= Pixmap height()
1532##
1533.
1534
1535If behavior is SkTransferFunctionBehavior::kRespect: converts source
1536pixels to a linear space before converting to dstInfo.
1537If behavior is SkTransferFunctionBehavior::kIgnore: source
1538pixels are treated as if they are linear, regardless of how they are encoded.
1539
1540#Param dstInfo  destination width, height, Color_Type, Alpha_Type, Color_Space ##
1541#Param dstPixels  destination pixel storage ##
1542#Param dstRowBytes  destination row length ##
1543#Param srcX  column index whose absolute value is less than width() ##
1544#Param srcY  row index whose absolute value is less than height() ##
1545#Param behavior  one of: SkTransferFunctionBehavior::kRespect,
1546                         SkTransferFunctionBehavior::kIgnore
1547##
1548
1549#Return  true if pixels are copied to dstPixels ##
1550
1551#Example
1552#ToDo example doesn't do anything interesting since info colorSpace is nullptr ##
1553#Image 3
1554void draw(SkCanvas* canvas) {
1555    SkImageInfo info = SkImageInfo::MakeN32Premul(image->width(), image->height(),
1556            canvas->imageInfo().colorSpace() ? SkColorSpace::MakeSRGB() : nullptr);
1557    std::vector<int32_t> srcPixels;
1558    srcPixels.resize(image->height() * image->width() * 4);
1559    SkPixmap pixmap(info, (const void*) &srcPixels.front(), image->width() * 4);
1560    image->readPixels(pixmap, 0, 0);
1561    SkTransferFunctionBehavior behavior = canvas->imageInfo().colorSpace() ?
1562            SkTransferFunctionBehavior::kRespect : SkTransferFunctionBehavior::kIgnore;
1563    std::vector<int32_t> dstPixels;
1564    dstPixels.resize(image->height() * image->width() * 4);
1565    int offset = 0;
1566    for (auto behavior : { SkTransferFunctionBehavior::kRespect,
1567                           SkTransferFunctionBehavior::kIgnore} ) {
1568        pixmap.readPixels(info, &dstPixels.front(), image->width() * 4, offset, 0, behavior);
1569        offset += 128;
1570    }
1571    SkBitmap bitmap;
1572    SkPixmap dstmap(info, &dstPixels.front(), image->width() * 4);
1573    bitmap.installPixels(dstmap);
1574    canvas->drawBitmap(bitmap, 0, 0);
1575}
1576##
1577
1578#SeeAlso erase SkBitmap::readPixels SkCanvas::drawBitmap SkCanvas::readPixels SkImage::readPixels SkSurface::readPixels
1579
1580##
1581
1582# ------------------------------------------------------------------------------
1583
1584#Method bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes) const
1585
1586#In Pixels
1587Copies a Rect of pixels to dstPixels. Copy starts at (0, 0), and does not
1588exceed Pixmap (width(), height()).
1589
1590dstInfo specifies width, height, Color_Type, Alpha_Type, and
1591Color_Space of destination. dstRowBytes specifics the gap from one destination
1592row to the next. Returns true if pixels are copied. Returns false if
1593dstInfo.addr() equals nullptr, or dstRowBytes is less than dstInfo.minRowBytes.
1594
1595Pixels are copied only if pixel conversion is possible. If Pixmap colorType is
1596kGray_8_SkColorType, or kAlpha_8_SkColorType; dstInfo.colorType must match.
1597If Pixmap colorType is kGray_8_SkColorType, dstInfo.colorSpace must match.
1598If Pixmap alphaType is kOpaque_SkAlphaType, dstInfo.alphaType must
1599match. If Pixmap colorSpace is nullptr, dstInfo.colorSpace must match. Returns
1600false if pixel conversion is not possible.
1601
1602Returns false if Pixmap width() or height() is zero or negative.
1603
1604#Param dstInfo  destination width, height, Color_Type, Alpha_Type, Color_Space ##
1605#Param dstPixels  destination pixel storage ##
1606#Param dstRowBytes  destination row length ##
1607
1608#Return  true if pixels are copied to dstPixels ##
1609
1610#Example
1611#Height 128
1612#Description
1613Transferring the gradient from 8 bits per component to 4 bits per component
1614creates visible banding.
1615##
1616    std::vector<int32_t> pixels;
1617    const int width = 256;
1618    const int height = 64;
1619    pixels.resize(height * width * 4);
1620    SkImageInfo srcInfo = SkImageInfo::MakeN32Premul(width, height);
1621    SkPixmap srcPixmap(srcInfo, (const void*) &pixels.front(), width * 4);
1622    SkColor  gradColors[] = { 0xFFAA3300, 0x7F881122 };
1623    SkPoint  gradPoints[] = { { 0, 0 }, { 256, 0 } };
1624    SkPaint paint;
1625    paint.setShader(SkGradientShader::MakeLinear(gradPoints, gradColors, nullptr,
1626                    SK_ARRAY_COUNT(gradColors), SkShader::kClamp_TileMode));
1627    SkBitmap bitmap;
1628    bitmap.installPixels(srcPixmap);
1629    SkCanvas srcCanvas(bitmap);
1630    srcCanvas.drawRect(SkRect::MakeWH(width, height), paint);
1631    canvas->drawBitmap(bitmap, 0, 0);
1632    std::vector<int32_t> dstPixels;
1633    dstPixels.resize(height * width * 2);
1634    SkImageInfo dstInfo = srcInfo.makeColorType(kARGB_4444_SkColorType);
1635    srcPixmap.readPixels(dstInfo, &dstPixels.front(), width * 2);
1636    SkPixmap dstPixmap(dstInfo, &dstPixels.front(), width * 2);
1637    bitmap.installPixels(dstPixmap);
1638    canvas->drawBitmap(bitmap, 0, 128);
1639##
1640
1641#SeeAlso erase SkBitmap::readPixels SkCanvas::drawBitmap SkCanvas::readPixels SkImage::readPixels SkSurface::readPixels
1642
1643##
1644
1645# ------------------------------------------------------------------------------
1646
1647#Method bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes, int srcX,
1648                    int srcY) const
1649
1650Copies a Rect of pixels to dstPixels. Copy starts at (srcX, srcY), and does not
1651exceed Pixmap (width(), height()).
1652
1653dstInfo specifies width, height, Color_Type, Alpha_Type, and
1654Color_Space of destination. dstRowBytes specifics the gap from one destination
1655row to the next. Returns true if pixels are copied. Returns false if
1656dstInfo.addr() equals nullptr, or dstRowBytes is less than dstInfo.minRowBytes.
1657
1658Pixels are copied only if pixel conversion is possible. If Pixmap colorType is
1659kGray_8_SkColorType, or kAlpha_8_SkColorType; dstInfo.colorType must match.
1660If Pixmap colorType is kGray_8_SkColorType, dstInfo.colorSpace must match.
1661If Pixmap alphaType is kOpaque_SkAlphaType, dstInfo.alphaType must
1662match. If Pixmap colorSpace is nullptr, dstInfo.colorSpace must match. Returns
1663false if pixel conversion is not possible.
1664
1665srcX and srcY may be negative to copy only top or left of source. Returns
1666false if Pixmap width() or height() is zero or negative. Returns false if:
1667
1668#Formula
1669abs(srcX) >= Pixmap width()
1670##
1671, or if
1672#Formula
1673abs(srcY) >= Pixmap height()
1674##
1675.
1676
1677#Param dstInfo  destination width, height, Color_Type, Alpha_Type, Color_Space ##
1678#Param dstPixels  destination pixel storage ##
1679#Param dstRowBytes  destination row length ##
1680#Param srcX  column index whose absolute value is less than width() ##
1681#Param srcY  row index whose absolute value is less than height() ##
1682
1683#Return  true if pixels are copied to dstPixels ##
1684
1685#Example
1686#Image 3
1687void draw(SkCanvas* canvas) {
1688    SkImageInfo info = SkImageInfo::MakeN32Premul(image->width(), image->height());
1689    std::vector<int32_t> srcPixels;
1690    const int rowBytes = image->width() * 4;
1691    srcPixels.resize(image->height() * rowBytes);
1692    SkPixmap pixmap(info, (const void*) &srcPixels.front(), rowBytes);
1693    image->readPixels(pixmap, 0, 0);
1694    for (int offset : { 32, 64, 96 } ) {
1695        std::vector<int32_t> dstPixels;
1696        dstPixels.resize(image->height() * rowBytes);
1697        pixmap.readPixels(info, &dstPixels.front(), rowBytes, offset, 0);
1698        SkBitmap bitmap;
1699        SkPixmap dstmap(info, &dstPixels.front(), rowBytes);
1700        bitmap.installPixels(dstmap);
1701        canvas->translate(32, 32);
1702        canvas->drawBitmap(bitmap, 0, 0);
1703    }
1704}
1705##
1706
1707#SeeAlso erase SkBitmap::readPixels SkCanvas::drawBitmap SkCanvas::readPixels SkImage::readPixels SkSurface::readPixels
1708
1709##
1710
1711# ------------------------------------------------------------------------------
1712
1713#Method bool readPixels(const SkPixmap& dst, int srcX, int srcY) const
1714
1715Copies a Rect of pixels to dst. Copy starts at (srcX, srcY), and does not
1716exceed Pixmap (width(), height()). dst specifies width, height, Color_Type,
1717Alpha_Type, and Color_Space of destination.  Returns true if pixels are copied.
1718Returns false if dst.addr() equals nullptr, or dst.rowBytes is less than
1719dst SkImageInfo::minRowBytes.
1720
1721Pixels are copied only if pixel conversion is possible. If Pixmap colorType is
1722kGray_8_SkColorType, or kAlpha_8_SkColorType; dst.info().colorType must match.
1723If Pixmap colorType is kGray_8_SkColorType, dst.info().colorSpace must match.
1724If Pixmap alphaType is kOpaque_SkAlphaType, dst.info().alphaType must
1725match. If Pixmap colorSpace is nullptr, dst.info().colorSpace must match. Returns
1726false if pixel conversion is not possible.
1727
1728srcX and srcY may be negative to copy only top or left of source. Returns
1729false Pixmap width() or height() is zero or negative. Returns false if:
1730
1731#Formula
1732abs(srcX) >= Pixmap width()
1733##
1734, or if
1735#Formula
1736abs(srcY) >= Pixmap height()
1737##
1738.
1739
1740#Param dst  Image_Info and pixel address to write to ##
1741#Param srcX  column index whose absolute value is less than width() ##
1742#Param srcY  row index whose absolute value is less than height() ##
1743
1744#Return  true if pixels are copied to dst ##
1745
1746#Example
1747#Image 3
1748void draw(SkCanvas* canvas) {
1749    SkImageInfo info = SkImageInfo::MakeN32Premul(image->width(), image->height());
1750    std::vector<int32_t> srcPixels;
1751    const int rowBytes = image->width() * 4;
1752    srcPixels.resize(image->height() * rowBytes);
1753    SkPixmap pixmap(info, (const void*) &srcPixels.front(), rowBytes);
1754    image->readPixels(pixmap, 0, 0);
1755    for (int offset : { 32, 64, 96 } ) {
1756        std::vector<int32_t> dstPixels;
1757        dstPixels.resize(image->height() * rowBytes);
1758        SkPixmap dstmap(info, &dstPixels.front(), rowBytes);
1759        pixmap.readPixels(dstmap, offset, 0);
1760        SkBitmap bitmap;
1761        bitmap.installPixels(dstmap);
1762        canvas->translate(32, 32);
1763        canvas->drawBitmap(bitmap, 0, 0);
1764    }
1765}
1766##
1767
1768#SeeAlso erase SkBitmap::readPixels SkCanvas::drawBitmap SkCanvas::readPixels SkImage::readPixels SkSurface::readPixels
1769
1770##
1771
1772# ------------------------------------------------------------------------------
1773
1774#Method bool readPixels(const SkPixmap& dst) const
1775
1776Copies pixels inside bounds() to dst. dst specifies width, height, Color_Type,
1777Alpha_Type, and Color_Space of destination.  Returns true if pixels are copied.
1778Returns false if dst.addr() equals nullptr, or dst.rowBytes is less than
1779dst SkImageInfo::minRowBytes.
1780
1781Pixels are copied only if pixel conversion is possible. If Pixmap colorType is
1782kGray_8_SkColorType, or kAlpha_8_SkColorType; dst Color_Type must match.
1783If Pixmap colorType is kGray_8_SkColorType, dst Color_Space must match.
1784If Pixmap alphaType is kOpaque_SkAlphaType, dst Alpha_Type must
1785match. If Pixmap colorSpace is nullptr, dst Color_Space must match. Returns
1786false if pixel conversion is not possible.
1787
1788Returns false if Pixmap width() or height() is zero or negative.
1789
1790#Param dst  Image_Info and pixel address to write to ##
1791
1792#Return  true if pixels are copied to dst ##
1793
1794#Example
1795#Image 3
1796void draw(SkCanvas* canvas) {
1797    SkImageInfo info = SkImageInfo::MakeN32Premul(image->width(), image->height());
1798    std::vector<int32_t> srcPixels;
1799    const int rowBytes = image->width() * 4;
1800    srcPixels.resize(image->height() * rowBytes);
1801    SkPixmap pixmap(info, (const void*) &srcPixels.front(), rowBytes);
1802    image->readPixels(pixmap, 0, 0);
1803    for (int index = 0; index < 3; ++index ) {
1804        std::vector<int32_t> dstPixels;
1805        dstPixels.resize(image->height() * rowBytes);
1806        SkPixmap dstmap(info, &dstPixels.front(), rowBytes);
1807        pixmap.readPixels(dstmap);
1808        SkBitmap bitmap;
1809        bitmap.installPixels(dstmap);
1810        canvas->translate(32, 32);
1811        canvas->drawBitmap(bitmap, 0, 0);
1812    }
1813}
1814##
1815
1816#SeeAlso erase SkBitmap::readPixels SkCanvas::drawBitmap SkCanvas::readPixels SkImage::readPixels SkSurface::readPixels
1817
1818##
1819
1820# ------------------------------------------------------------------------------
1821
1822#Method bool scalePixels(const SkPixmap& dst, SkFilterQuality filterQuality) const
1823
1824#In Pixels
1825#Line # scales and converts pixels ##
1826Copies Bitmap to dst, scaling pixels to fit dst.width() and dst.height(), and
1827converting pixels to match dst.colorType and dst.alphaType. Returns true if
1828pixels are copied. Returns false if dst.addr() is nullptr, or dst.rowBytes is
1829less than dst SkImageInfo::minRowBytes.
1830
1831Pixels are copied only if pixel conversion is possible. If Pixmap colorType is
1832kGray_8_SkColorType, or kAlpha_8_SkColorType; dst Color_Type must match.
1833If Pixmap colorType is kGray_8_SkColorType, dst Color_Space must match.
1834If Pixmap alphaType is kOpaque_SkAlphaType, dst Alpha_Type must
1835match. If Pixmap colorSpace is nullptr, dst Color_Space must match. Returns
1836false if pixel conversion is not possible.
1837
1838Returns false if Bitmap width() or height() is zero or negative.
1839
1840Scales the image, with filterQuality, to match dst.width() and dst.height().
1841filterQuality kNone_SkFilterQuality is fastest, typically implemented with
1842Filter_Quality_Nearest_Neighbor. kLow_SkFilterQuality is typically implemented with
1843Filter_Quality_Bilerp. kMedium_SkFilterQuality is typically implemented with
1844Filter_Quality_Bilerp, and Filter_Quality_MipMap when size is reduced.
1845kHigh_SkFilterQuality is slowest, typically implemented with Filter_Quality_BiCubic.
1846
1847#Param dst  Image_Info and pixel address to write to ##
1848#Param filterQuality  one of: kNone_SkFilterQuality, kLow_SkFilterQuality,
1849                      kMedium_SkFilterQuality, kHigh_SkFilterQuality
1850##
1851
1852#Return  true if pixels are scaled to fit dst ##
1853
1854#Example
1855#Image 3
1856void draw(SkCanvas* canvas) {
1857    SkImageInfo info = SkImageInfo::MakeN32Premul(image->width(), image->height());
1858    std::vector<int32_t> srcPixels;
1859    int rowBytes = image->width() * 4;
1860    srcPixels.resize(image->height() * rowBytes);
1861    SkPixmap pixmap(info, (const void*) &srcPixels.front(), rowBytes);
1862    image->readPixels(pixmap, 0, 0);
1863    for (int offset : { 32, 64, 96 } ) {
1864        info = SkImageInfo::MakeN32Premul(image->width() + offset, image->height());
1865        rowBytes = info.width() * 4;
1866        std::vector<int32_t> dstPixels;
1867        dstPixels.resize(image->height() * rowBytes);
1868        SkPixmap dstmap(info, &dstPixels.front(), rowBytes);
1869        pixmap.scalePixels(dstmap, kMedium_SkFilterQuality);
1870        SkBitmap bitmap;
1871        bitmap.installPixels(dstmap);
1872        canvas->translate(32, 32);
1873        canvas->drawBitmap(bitmap, 0, 0);
1874    }
1875}
1876##
1877
1878#SeeAlso SkCanvas::drawBitmap SkImage::scalePixels
1879
1880##
1881
1882# ------------------------------------------------------------------------------
1883
1884#Method bool erase(SkColor color, const SkIRect& subset) const
1885
1886#In Pixels
1887#Line # writes Color to pixels ##
1888Writes color to pixels bounded by subset; returns true on success.
1889Returns false if colorType is kUnknown_SkColorType, or if subset does
1890not intersect bounds().
1891
1892#Param color  Unpremultiplied Color to write ##
1893#Param subset bounding integer Rect of written pixels ##
1894
1895#Return  true if pixels are changed ##
1896
1897#Example
1898#Height 50
1899    uint32_t storage[2];
1900    SkImageInfo info = SkImageInfo::MakeN32Premul(1, 2);
1901    SkPixmap pixmap(info, storage, info.minRowBytes());
1902    pixmap.erase(SK_ColorBLUE, {0, 0, 1, 1});
1903    pixmap.erase(SK_ColorRED, {0, 1, 1, 2});
1904    SkBitmap bitmap;
1905    canvas->scale(20, 20);
1906    bitmap.installPixels(pixmap);
1907    canvas->drawBitmap(bitmap, 0, 0);
1908##
1909
1910#SeeAlso SkBitmap::erase SkCanvas::clear SkCanvas::drawColor
1911
1912##
1913
1914# ------------------------------------------------------------------------------
1915
1916#Method bool erase(SkColor color) const
1917
1918Writes color to pixels inside bounds(); returns true on success.
1919Returns false if colorType is kUnknown_SkColorType, or if bounds()
1920is empty.
1921
1922#Param color  Unpremultiplied Color to write ##
1923
1924#Return  true if pixels are changed ##
1925
1926#Example
1927#Height 50
1928    uint32_t storage[2];
1929    SkImageInfo info = SkImageInfo::MakeN32Premul(1, 2);
1930    SkPixmap pixmap(info, storage, info.minRowBytes());
1931    pixmap.erase(SK_ColorBLUE);
1932    SkBitmap bitmap;
1933    canvas->scale(20, 20);
1934    bitmap.installPixels(pixmap);
1935    canvas->drawBitmap(bitmap, 0, 0);
1936##
1937
1938#SeeAlso SkBitmap::erase SkCanvas::clear SkCanvas::drawColor
1939
1940##
1941
1942# ------------------------------------------------------------------------------
1943
1944#Method bool erase(const SkColor4f& color, const SkIRect* subset = nullptr) const
1945
1946Writes color to pixels bounded by subset; returns true on success.
1947if subset is nullptr, writes colors pixels inside bounds(). Returns false if
1948colorType is kUnknown_SkColorType, if subset is not nullptr and does
1949not intersect bounds(), or if subset is nullptr and bounds() is empty.
1950
1951#Param color  Unpremultiplied Color to write ##
1952#Param subset  bounding integer Rect of pixels to write; may be nullptr ##
1953
1954#Return  true if pixels are changed ##
1955
1956#Example
1957#Height 50
1958    uint32_t storage[2];
1959    SkImageInfo info = SkImageInfo::MakeN32Premul(1, 2);
1960    SkPixmap pixmap(info, storage, info.minRowBytes());
1961    SkIRect topPixelBounds = {0, 0, 1, 1};
1962    pixmap.erase({ 0.65f, 0.45f, 0.25f, 1 }, &topPixelBounds);
1963    SkIRect bottomPixelBounds = {0, 1, 1, 2};
1964    pixmap.erase({ 0.25f, 0.65f, 0.45f, 1 }, &bottomPixelBounds);
1965    SkBitmap bitmap;
1966    canvas->scale(20, 20);
1967    bitmap.installPixels(pixmap);
1968    canvas->drawBitmap(bitmap, 0, 0);
1969##
1970
1971#SeeAlso SkBitmap::erase SkCanvas::clear SkCanvas::drawColor
1972
1973##
1974
1975#Class SkPixmap ##
1976
1977#Topic Pixmap ##
1978