1/*
2 * Copyright 2015 Google Inc.
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 SkPixmap_DEFINED
9#define SkPixmap_DEFINED
10
11#include "include/core/SkColor.h"
12#include "include/core/SkFilterQuality.h"
13#include "include/core/SkImageInfo.h"
14
15class SkData;
16struct SkMask;
17
18/** \class SkPixmap
19 SkPixmap provides a utility to pair SkImageInfo with pixels and row bytes.
20 SkPixmap is a low level class which provides convenience functions to access
21 raster destinations. SkCanvas can not draw SkPixmap, nor does SkPixmap provide
22 a direct drawing destination.
23
24 Use SkBitmap to draw pixels referenced by SkPixmap; use SkSurface to draw into
25 pixels referenced by SkPixmap.
26
27 SkPixmap does not try to manage the lifetime of the pixel memory. Use SkPixelRef
28 to manage pixel memory; SkPixelRef is safe across threads.
29*/
30class SK_API SkPixmap {
31public:
32
33 /** Creates an empty SkPixmap without pixels, with kUnknown_SkColorType, with
34 kUnknown_SkAlphaType, and with a width and height of zero. Use
35 reset() to associate pixels, SkColorType, SkAlphaType, width, and height
36 after SkPixmap has been created.
37
38 @return empty SkPixmap
39 */
40 SkPixmap()
41 : fPixels(nullptr), fRowBytes(0), fInfo(SkImageInfo::MakeUnknown(0, 0))
42 {}
43
44 /** Creates SkPixmap from info width, height, SkAlphaType, and SkColorType.
45 addr points to pixels, or nullptr. rowBytes should be info.width() times
46 info.bytesPerPixel(), or larger.
47
48 No parameter checking is performed; it is up to the caller to ensure that
49 addr and rowBytes agree with info.
50
51 The memory lifetime of pixels is managed by the caller. When SkPixmap goes
52 out of scope, addr is unaffected.
53
54 SkPixmap may be later modified by reset() to change its size, pixel type, or
55 storage.
56
57 @param info width, height, SkAlphaType, SkColorType of SkImageInfo
58 @param addr pointer to pixels allocated by caller; may be nullptr
59 @param rowBytes size of one row of addr; width times pixel size, or larger
60 @return initialized SkPixmap
61 */
62 SkPixmap(const SkImageInfo& info, const void* addr, size_t rowBytes)
63 : fPixels(addr), fRowBytes(rowBytes), fInfo(info)
64 {}
65
66 /** Sets width, height, row bytes to zero; pixel address to nullptr; SkColorType to
67 kUnknown_SkColorType; and SkAlphaType to kUnknown_SkAlphaType.
68
69 The prior pixels are unaffected; it is up to the caller to release pixels
70 memory if desired.
71
72 example: https://fiddle.skia.org/c/@Pixmap_reset
73 */
74 void reset();
75
76 /** Sets width, height, SkAlphaType, and SkColorType from info.
77 Sets pixel address from addr, which may be nullptr.
78 Sets row bytes from rowBytes, which should be info.width() times
79 info.bytesPerPixel(), or larger.
80
81 Does not check addr. Asserts if built with SK_DEBUG defined and if rowBytes is
82 too small to hold one row of pixels.
83
84 The memory lifetime pixels are managed by the caller. When SkPixmap goes
85 out of scope, addr is unaffected.
86
87 @param info width, height, SkAlphaType, SkColorType of SkImageInfo
88 @param addr pointer to pixels allocated by caller; may be nullptr
89 @param rowBytes size of one row of addr; width times pixel size, or larger
90
91 example: https://fiddle.skia.org/c/@Pixmap_reset_2
92 */
93 void reset(const SkImageInfo& info, const void* addr, size_t rowBytes);
94
95 /** Changes SkColorSpace in SkImageInfo; preserves width, height, SkAlphaType, and
96 SkColorType in SkImage, and leaves pixel address and row bytes unchanged.
97 SkColorSpace reference count is incremented.
98
99 @param colorSpace SkColorSpace moved to SkImageInfo
100
101 example: https://fiddle.skia.org/c/@Pixmap_setColorSpace
102 */
103 void setColorSpace(sk_sp<SkColorSpace> colorSpace);
104
105 /** Deprecated.
106 */
107 bool SK_WARN_UNUSED_RESULT reset(const SkMask& mask);
108
109 /** Sets subset width, height, pixel address to intersection of SkPixmap with area,
110 if intersection is not empty; and return true. Otherwise, leave subset unchanged
111 and return false.
112
113 Failing to read the return value generates a compile time warning.
114
115 @param subset storage for width, height, pixel address of intersection
116 @param area bounds to intersect with SkPixmap
117 @return true if intersection of SkPixmap and area is not empty
118 */
119 bool SK_WARN_UNUSED_RESULT extractSubset(SkPixmap* subset, const SkIRect& area) const;
120
121 /** Returns width, height, SkAlphaType, SkColorType, and SkColorSpace.
122
123 @return reference to SkImageInfo
124 */
125 const SkImageInfo& info() const { return fInfo; }
126
127 /** Returns row bytes, the interval from one pixel row to the next. Row bytes
128 is at least as large as: width() * info().bytesPerPixel().
129
130 Returns zero if colorType() is kUnknown_SkColorType.
131 It is up to the SkBitmap creator to ensure that row bytes is a useful value.
132
133 @return byte length of pixel row
134 */
135 size_t rowBytes() const { return fRowBytes; }
136
137 /** Returns pixel address, the base address corresponding to the pixel origin.
138
139 It is up to the SkPixmap creator to ensure that pixel address is a useful value.
140
141 @return pixel address
142 */
143 const void* addr() const { return fPixels; }
144
145 /** Returns pixel count in each pixel row. Should be equal or less than:
146 rowBytes() / info().bytesPerPixel().
147
148 @return pixel width in SkImageInfo
149 */
150 int width() const { return fInfo.width(); }
151
152 /** Returns pixel row count.
153
154 @return pixel height in SkImageInfo
155 */
156 int height() const { return fInfo.height(); }
157
158 /**
159 * Return the dimensions of the pixmap (from its ImageInfo)
160 */
161 SkISize dimensions() const { return fInfo.dimensions(); }
162
163 SkColorType colorType() const { return fInfo.colorType(); }
164
165 SkAlphaType alphaType() const { return fInfo.alphaType(); }
166
167 /** Returns SkColorSpace, the range of colors, associated with SkImageInfo. The
168 reference count of SkColorSpace is unchanged. The returned SkColorSpace is
169 immutable.
170
171 @return SkColorSpace in SkImageInfo, or nullptr
172 */
173 SkColorSpace* colorSpace() const { return fInfo.colorSpace(); }
174
175 /** Returns smart pointer to SkColorSpace, the range of colors, associated with
176 SkImageInfo. The smart pointer tracks the number of objects sharing this
177 SkColorSpace reference so the memory is released when the owners destruct.
178
179 The returned SkColorSpace is immutable.
180
181 @return SkColorSpace in SkImageInfo wrapped in a smart pointer
182 */
183 sk_sp<SkColorSpace> refColorSpace() const { return fInfo.refColorSpace(); }
184
185 /** Returns true if SkAlphaType is kOpaque_SkAlphaType.
186 Does not check if SkColorType allows alpha, or if any pixel value has
187 transparency.
188
189 @return true if SkImageInfo has opaque SkAlphaType
190 */
191 bool isOpaque() const { return fInfo.isOpaque(); }
192
193 /** Returns SkIRect { 0, 0, width(), height() }.
194
195 @return integral rectangle from origin to width() and height()
196 */
197 SkIRect bounds() const { return SkIRect::MakeWH(this->width(), this->height()); }
198
199 /** Returns number of pixels that fit on row. Should be greater than or equal to
200 width().
201
202 @return maximum pixels per row
203 */
204 int rowBytesAsPixels() const { return int(fRowBytes >> this->shiftPerPixel()); }
205
206 /** Returns bit shift converting row bytes to row pixels.
207 Returns zero for kUnknown_SkColorType.
208
209 @return one of: 0, 1, 2, 3; left shift to convert pixels to bytes
210 */
211 int shiftPerPixel() const { return fInfo.shiftPerPixel(); }
212
213 /** Returns minimum memory required for pixel storage.
214 Does not include unused memory on last row when rowBytesAsPixels() exceeds width().
215 Returns SIZE_MAX if result does not fit in size_t.
216 Returns zero if height() or width() is 0.
217 Returns height() times rowBytes() if colorType() is kUnknown_SkColorType.
218
219 @return size in bytes of image buffer
220 */
221 size_t computeByteSize() const { return fInfo.computeByteSize(fRowBytes); }
222
223 /** Returns true if all pixels are opaque. SkColorType determines how pixels
224 are encoded, and whether pixel describes alpha. Returns true for SkColorType
225 without alpha in each pixel; for other SkColorType, returns true if all
226 pixels have alpha values equivalent to 1.0 or greater.
227
228 For SkColorType kRGB_565_SkColorType or kGray_8_SkColorType: always
229 returns true. For SkColorType kAlpha_8_SkColorType, kBGRA_8888_SkColorType,
230 kRGBA_8888_SkColorType: returns true if all pixel alpha values are 255.
231 For SkColorType kARGB_4444_SkColorType: returns true if all pixel alpha values are 15.
232 For kRGBA_F16_SkColorType: returns true if all pixel alpha values are 1.0 or
233 greater.
234
235 Returns false for kUnknown_SkColorType.
236
237 @return true if all pixels have opaque values or SkColorType is opaque
238
239 example: https://fiddle.skia.org/c/@Pixmap_computeIsOpaque
240 */
241 bool computeIsOpaque() const;
242
243 /** Returns pixel at (x, y) as unpremultiplied color.
244 Returns black with alpha if SkColorType is kAlpha_8_SkColorType.
245
246 Input is not validated: out of bounds values of x or y trigger an assert() if
247 built with SK_DEBUG defined; and returns undefined values or may crash if
248 SK_RELEASE is defined. Fails if SkColorType is kUnknown_SkColorType or
249 pixel address is nullptr.
250
251 SkColorSpace in SkImageInfo is ignored. Some color precision may be lost in the
252 conversion to unpremultiplied color; original pixel data may have additional
253 precision.
254
255 @param x column index, zero or greater, and less than width()
256 @param y row index, zero or greater, and less than height()
257 @return pixel converted to unpremultiplied color
258
259 example: https://fiddle.skia.org/c/@Pixmap_getColor
260 */
261 SkColor getColor(int x, int y) const;
262
263 /** Look up the pixel at (x,y) and return its alpha component, normalized to [0..1].
264 This is roughly equivalent to SkGetColorA(getColor()), but can be more efficent
265 (and more precise if the pixels store more than 8 bits per component).
266
267 @param x column index, zero or greater, and less than width()
268 @param y row index, zero or greater, and less than height()
269 @return alpha converted to normalized float
270 */
271 float getAlphaf(int x, int y) const;
272
273 /** Returns readable pixel address at (x, y). Returns nullptr if SkPixelRef is nullptr.
274
275 Input is not validated: out of bounds values of x or y trigger an assert() if
276 built with SK_DEBUG defined. Returns nullptr if SkColorType is kUnknown_SkColorType.
277
278 Performs a lookup of pixel size; for better performance, call
279 one of: addr8, addr16, addr32, addr64, or addrF16().
280
281 @param x column index, zero or greater, and less than width()
282 @param y row index, zero or greater, and less than height()
283 @return readable generic pointer to pixel
284 */
285 const void* addr(int x, int y) const {
286 return (const char*)fPixels + fInfo.computeOffset(x, y, fRowBytes);
287 }
288
289 /** Returns readable base pixel address. Result is addressable as unsigned 8-bit bytes.
290 Will trigger an assert() if SkColorType is not kAlpha_8_SkColorType or
291 kGray_8_SkColorType, and is built with SK_DEBUG defined.
292
293 One byte corresponds to one pixel.
294
295 @return readable unsigned 8-bit pointer to pixels
296 */
297 const uint8_t* addr8() const {
298 SkASSERT(1 == fInfo.bytesPerPixel());
299 return reinterpret_cast<const uint8_t*>(fPixels);
300 }
301
302 /** Returns readable base pixel address. Result is addressable as unsigned 16-bit words.
303 Will trigger an assert() if SkColorType is not kRGB_565_SkColorType or
304 kARGB_4444_SkColorType, and is built with SK_DEBUG defined.
305
306 One word corresponds to one pixel.
307
308 @return readable unsigned 16-bit pointer to pixels
309 */
310 const uint16_t* addr16() const {
311 SkASSERT(2 == fInfo.bytesPerPixel());
312 return reinterpret_cast<const uint16_t*>(fPixels);
313 }
314
315 /** Returns readable base pixel address. Result is addressable as unsigned 32-bit words.
316 Will trigger an assert() if SkColorType is not kRGBA_8888_SkColorType or
317 kBGRA_8888_SkColorType, and is built with SK_DEBUG defined.
318
319 One word corresponds to one pixel.
320
321 @return readable unsigned 32-bit pointer to pixels
322 */
323 const uint32_t* addr32() const {
324 SkASSERT(4 == fInfo.bytesPerPixel());
325 return reinterpret_cast<const uint32_t*>(fPixels);
326 }
327
328 /** Returns readable base pixel address. Result is addressable as unsigned 64-bit words.
329 Will trigger an assert() if SkColorType is not kRGBA_F16_SkColorType and is built
330 with SK_DEBUG defined.
331
332 One word corresponds to one pixel.
333
334 @return readable unsigned 64-bit pointer to pixels
335 */
336 const uint64_t* addr64() const {
337 SkASSERT(8 == fInfo.bytesPerPixel());
338 return reinterpret_cast<const uint64_t*>(fPixels);
339 }
340
341 /** Returns readable base pixel address. Result is addressable as unsigned 16-bit words.
342 Will trigger an assert() if SkColorType is not kRGBA_F16_SkColorType and is built
343 with SK_DEBUG defined.
344
345 Each word represents one color component encoded as a half float.
346 Four words correspond to one pixel.
347
348 @return readable unsigned 16-bit pointer to first component of pixels
349 */
350 const uint16_t* addrF16() const {
351 SkASSERT(8 == fInfo.bytesPerPixel());
352 SkASSERT(kRGBA_F16_SkColorType == fInfo.colorType() ||
353 kRGBA_F16Norm_SkColorType == fInfo.colorType());
354 return reinterpret_cast<const uint16_t*>(fPixels);
355 }
356
357 /** Returns readable pixel address at (x, y).
358
359 Input is not validated: out of bounds values of x or y trigger an assert() if
360 built with SK_DEBUG defined.
361
362 Will trigger an assert() if SkColorType is not kAlpha_8_SkColorType or
363 kGray_8_SkColorType, and is built with SK_DEBUG defined.
364
365 @param x column index, zero or greater, and less than width()
366 @param y row index, zero or greater, and less than height()
367 @return readable unsigned 8-bit pointer to pixel at (x, y)
368 */
369 const uint8_t* addr8(int x, int y) const {
370 SkASSERT((unsigned)x < (unsigned)fInfo.width());
371 SkASSERT((unsigned)y < (unsigned)fInfo.height());
372 return (const uint8_t*)((const char*)this->addr8() + y * fRowBytes + (x << 0));
373 }
374
375 /** Returns readable pixel address at (x, y).
376
377 Input is not validated: out of bounds values of x or y trigger an assert() if
378 built with SK_DEBUG defined.
379
380 Will trigger an assert() if SkColorType is not kRGB_565_SkColorType or
381 kARGB_4444_SkColorType, and is built with SK_DEBUG defined.
382
383 @param x column index, zero or greater, and less than width()
384 @param y row index, zero or greater, and less than height()
385 @return readable unsigned 16-bit pointer to pixel at (x, y)
386 */
387 const uint16_t* addr16(int x, int y) const {
388 SkASSERT((unsigned)x < (unsigned)fInfo.width());
389 SkASSERT((unsigned)y < (unsigned)fInfo.height());
390 return (const uint16_t*)((const char*)this->addr16() + y * fRowBytes + (x << 1));
391 }
392
393 /** Returns readable pixel address at (x, y).
394
395 Input is not validated: out of bounds values of x or y trigger an assert() if
396 built with SK_DEBUG defined.
397
398 Will trigger an assert() if SkColorType is not kRGBA_8888_SkColorType or
399 kBGRA_8888_SkColorType, and is built with SK_DEBUG defined.
400
401 @param x column index, zero or greater, and less than width()
402 @param y row index, zero or greater, and less than height()
403 @return readable unsigned 32-bit pointer to pixel at (x, y)
404 */
405 const uint32_t* addr32(int x, int y) const {
406 SkASSERT((unsigned)x < (unsigned)fInfo.width());
407 SkASSERT((unsigned)y < (unsigned)fInfo.height());
408 return (const uint32_t*)((const char*)this->addr32() + y * fRowBytes + (x << 2));
409 }
410
411 /** Returns readable pixel address at (x, y).
412
413 Input is not validated: out of bounds values of x or y trigger an assert() if
414 built with SK_DEBUG defined.
415
416 Will trigger an assert() if SkColorType is not kRGBA_F16_SkColorType and is built
417 with SK_DEBUG defined.
418
419 @param x column index, zero or greater, and less than width()
420 @param y row index, zero or greater, and less than height()
421 @return readable unsigned 64-bit pointer to pixel at (x, y)
422 */
423 const uint64_t* addr64(int x, int y) const {
424 SkASSERT((unsigned)x < (unsigned)fInfo.width());
425 SkASSERT((unsigned)y < (unsigned)fInfo.height());
426 return (const uint64_t*)((const char*)this->addr64() + y * fRowBytes + (x << 3));
427 }
428
429 /** Returns readable pixel address at (x, y).
430
431 Input is not validated: out of bounds values of x or y trigger an assert() if
432 built with SK_DEBUG defined.
433
434 Will trigger an assert() if SkColorType is not kRGBA_F16_SkColorType and is built
435 with SK_DEBUG defined.
436
437 Each unsigned 16-bit word represents one color component encoded as a half float.
438 Four words correspond to one pixel.
439
440 @param x column index, zero or greater, and less than width()
441 @param y row index, zero or greater, and less than height()
442 @return readable unsigned 16-bit pointer to pixel component at (x, y)
443 */
444 const uint16_t* addrF16(int x, int y) const {
445 SkASSERT(kRGBA_F16_SkColorType == fInfo.colorType() ||
446 kRGBA_F16Norm_SkColorType == fInfo.colorType());
447 return reinterpret_cast<const uint16_t*>(this->addr64(x, y));
448 }
449
450 /** Returns writable base pixel address.
451
452 @return writable generic base pointer to pixels
453 */
454 void* writable_addr() const { return const_cast<void*>(fPixels); }
455
456 /** Returns writable pixel address at (x, y).
457
458 Input is not validated: out of bounds values of x or y trigger an assert() if
459 built with SK_DEBUG defined. Returns zero if SkColorType is kUnknown_SkColorType.
460
461 @param x column index, zero or greater, and less than width()
462 @param y row index, zero or greater, and less than height()
463 @return writable generic pointer to pixel
464 */
465 void* writable_addr(int x, int y) const {
466 return const_cast<void*>(this->addr(x, y));
467 }
468
469 /** Returns writable pixel address at (x, y). Result is addressable as unsigned
470 8-bit bytes. Will trigger an assert() if SkColorType is not kAlpha_8_SkColorType
471 or kGray_8_SkColorType, and is built with SK_DEBUG defined.
472
473 One byte corresponds to one pixel.
474
475 @param x column index, zero or greater, and less than width()
476 @param y row index, zero or greater, and less than height()
477 @return writable unsigned 8-bit pointer to pixels
478 */
479 uint8_t* writable_addr8(int x, int y) const {
480 return const_cast<uint8_t*>(this->addr8(x, y));
481 }
482
483 /** Returns writable_addr pixel address at (x, y). Result is addressable as unsigned
484 16-bit words. Will trigger an assert() if SkColorType is not kRGB_565_SkColorType
485 or kARGB_4444_SkColorType, and is built with SK_DEBUG defined.
486
487 One word corresponds to one pixel.
488
489 @param x column index, zero or greater, and less than width()
490 @param y row index, zero or greater, and less than height()
491 @return writable unsigned 16-bit pointer to pixel
492 */
493 uint16_t* writable_addr16(int x, int y) const {
494 return const_cast<uint16_t*>(this->addr16(x, y));
495 }
496
497 /** Returns writable pixel address at (x, y). Result is addressable as unsigned
498 32-bit words. Will trigger an assert() if SkColorType is not
499 kRGBA_8888_SkColorType or kBGRA_8888_SkColorType, and is built with SK_DEBUG
500 defined.
501
502 One word corresponds to one pixel.
503
504 @param x column index, zero or greater, and less than width()
505 @param y row index, zero or greater, and less than height()
506 @return writable unsigned 32-bit pointer to pixel
507 */
508 uint32_t* writable_addr32(int x, int y) const {
509 return const_cast<uint32_t*>(this->addr32(x, y));
510 }
511
512 /** Returns writable pixel address at (x, y). Result is addressable as unsigned
513 64-bit words. Will trigger an assert() if SkColorType is not
514 kRGBA_F16_SkColorType and is built with SK_DEBUG defined.
515
516 One word corresponds to one pixel.
517
518 @param x column index, zero or greater, and less than width()
519 @param y row index, zero or greater, and less than height()
520 @return writable unsigned 64-bit pointer to pixel
521 */
522 uint64_t* writable_addr64(int x, int y) const {
523 return const_cast<uint64_t*>(this->addr64(x, y));
524 }
525
526 /** Returns writable pixel address at (x, y). Result is addressable as unsigned
527 16-bit words. Will trigger an assert() if SkColorType is not
528 kRGBA_F16_SkColorType and is built with SK_DEBUG defined.
529
530 Each word represents one color component encoded as a half float.
531 Four words correspond to one pixel.
532
533 @param x column index, zero or greater, and less than width()
534 @param y row index, zero or greater, and less than height()
535 @return writable unsigned 16-bit pointer to first component of pixel
536 */
537 uint16_t* writable_addrF16(int x, int y) const {
538 return reinterpret_cast<uint16_t*>(writable_addr64(x, y));
539 }
540
541 /** Copies a SkRect of pixels to dstPixels. Copy starts at (0, 0), and does not
542 exceed SkPixmap (width(), height()).
543
544 dstInfo specifies width, height, SkColorType, SkAlphaType, and
545 SkColorSpace of destination. dstRowBytes specifics the gap from one destination
546 row to the next. Returns true if pixels are copied. Returns false if
547 dstInfo address equals nullptr, or dstRowBytes is less than dstInfo.minRowBytes().
548
549 Pixels are copied only if pixel conversion is possible. If SkPixmap colorType() is
550 kGray_8_SkColorType, or kAlpha_8_SkColorType; dstInfo.colorType() must match.
551 If SkPixmap colorType() is kGray_8_SkColorType, dstInfo.colorSpace() must match.
552 If SkPixmap alphaType() is kOpaque_SkAlphaType, dstInfo.alphaType() must
553 match. If SkPixmap colorSpace() is nullptr, dstInfo.colorSpace() must match. Returns
554 false if pixel conversion is not possible.
555
556 Returns false if SkPixmap width() or height() is zero or negative.
557
558 @param dstInfo destination width, height, SkColorType, SkAlphaType, SkColorSpace
559 @param dstPixels destination pixel storage
560 @param dstRowBytes destination row length
561 @return true if pixels are copied to dstPixels
562 */
563 bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes) const {
564 return this->readPixels(dstInfo, dstPixels, dstRowBytes, 0, 0);
565 }
566
567 /** Copies a SkRect of pixels to dstPixels. Copy starts at (srcX, srcY), and does not
568 exceed SkPixmap (width(), height()).
569
570 dstInfo specifies width, height, SkColorType, SkAlphaType, and
571 SkColorSpace of destination. dstRowBytes specifics the gap from one destination
572 row to the next. Returns true if pixels are copied. Returns false if
573 dstInfo address equals nullptr, or dstRowBytes is less than dstInfo.minRowBytes().
574
575 Pixels are copied only if pixel conversion is possible. If SkPixmap colorType() is
576 kGray_8_SkColorType, or kAlpha_8_SkColorType; dstInfo.colorType() must match.
577 If SkPixmap colorType() is kGray_8_SkColorType, dstInfo.colorSpace() must match.
578 If SkPixmap alphaType() is kOpaque_SkAlphaType, dstInfo.alphaType() must
579 match. If SkPixmap colorSpace() is nullptr, dstInfo.colorSpace() must match. Returns
580 false if pixel conversion is not possible.
581
582 srcX and srcY may be negative to copy only top or left of source. Returns
583 false if SkPixmap width() or height() is zero or negative. Returns false if:
584 abs(srcX) >= Pixmap width(), or if abs(srcY) >= Pixmap height().
585
586 @param dstInfo destination width, height, SkColorType, SkAlphaType, SkColorSpace
587 @param dstPixels destination pixel storage
588 @param dstRowBytes destination row length
589 @param srcX column index whose absolute value is less than width()
590 @param srcY row index whose absolute value is less than height()
591 @return true if pixels are copied to dstPixels
592 */
593 bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes, int srcX,
594 int srcY) const;
595
596 /** Copies a SkRect of pixels to dst. Copy starts at (srcX, srcY), and does not
597 exceed SkPixmap (width(), height()). dst specifies width, height, SkColorType,
598 SkAlphaType, and SkColorSpace of destination. Returns true if pixels are copied.
599 Returns false if dst address equals nullptr, or dst.rowBytes() is less than
600 dst SkImageInfo::minRowBytes.
601
602 Pixels are copied only if pixel conversion is possible. If SkPixmap colorType() is
603 kGray_8_SkColorType, or kAlpha_8_SkColorType; dst.info().colorType must match.
604 If SkPixmap colorType() is kGray_8_SkColorType, dst.info().colorSpace must match.
605 If SkPixmap alphaType() is kOpaque_SkAlphaType, dst.info().alphaType must
606 match. If SkPixmap colorSpace() is nullptr, dst.info().colorSpace must match. Returns
607 false if pixel conversion is not possible.
608
609 srcX and srcY may be negative to copy only top or left of source. Returns
610 false SkPixmap width() or height() is zero or negative. Returns false if:
611 abs(srcX) >= Pixmap width(), or if abs(srcY) >= Pixmap height().
612
613 @param dst SkImageInfo and pixel address to write to
614 @param srcX column index whose absolute value is less than width()
615 @param srcY row index whose absolute value is less than height()
616 @return true if pixels are copied to dst
617 */
618 bool readPixels(const SkPixmap& dst, int srcX, int srcY) const {
619 return this->readPixels(dst.info(), dst.writable_addr(), dst.rowBytes(), srcX, srcY);
620 }
621
622 /** Copies pixels inside bounds() to dst. dst specifies width, height, SkColorType,
623 SkAlphaType, and SkColorSpace of destination. Returns true if pixels are copied.
624 Returns false if dst address equals nullptr, or dst.rowBytes() is less than
625 dst SkImageInfo::minRowBytes.
626
627 Pixels are copied only if pixel conversion is possible. If SkPixmap colorType() is
628 kGray_8_SkColorType, or kAlpha_8_SkColorType; dst SkColorType must match.
629 If SkPixmap colorType() is kGray_8_SkColorType, dst SkColorSpace must match.
630 If SkPixmap alphaType() is kOpaque_SkAlphaType, dst SkAlphaType must
631 match. If SkPixmap colorSpace() is nullptr, dst SkColorSpace must match. Returns
632 false if pixel conversion is not possible.
633
634 Returns false if SkPixmap width() or height() is zero or negative.
635
636 @param dst SkImageInfo and pixel address to write to
637 @return true if pixels are copied to dst
638 */
639 bool readPixels(const SkPixmap& dst) const {
640 return this->readPixels(dst.info(), dst.writable_addr(), dst.rowBytes(), 0, 0);
641 }
642
643 /** Copies SkBitmap to dst, scaling pixels to fit dst.width() and dst.height(), and
644 converting pixels to match dst.colorType() and dst.alphaType(). Returns true if
645 pixels are copied. Returns false if dst address is nullptr, or dst.rowBytes() is
646 less than dst SkImageInfo::minRowBytes.
647
648 Pixels are copied only if pixel conversion is possible. If SkPixmap colorType() is
649 kGray_8_SkColorType, or kAlpha_8_SkColorType; dst SkColorType must match.
650 If SkPixmap colorType() is kGray_8_SkColorType, dst SkColorSpace must match.
651 If SkPixmap alphaType() is kOpaque_SkAlphaType, dst SkAlphaType must
652 match. If SkPixmap colorSpace() is nullptr, dst SkColorSpace must match. Returns
653 false if pixel conversion is not possible.
654
655 Returns false if SkBitmap width() or height() is zero or negative.
656
657 Scales the image, with filterQuality, to match dst.width() and dst.height().
658 filterQuality kNone_SkFilterQuality is fastest, typically implemented with
659 nearest neighbor filter. kLow_SkFilterQuality is typically implemented with
660 bilerp filter. kMedium_SkFilterQuality is typically implemented with
661 bilerp filter, and mip-map filter when size is reduced.
662 kHigh_SkFilterQuality is slowest, typically implemented with bicubic filter.
663
664 @param dst SkImageInfo and pixel address to write to
665 @return true if pixels are scaled to fit dst
666
667 example: https://fiddle.skia.org/c/@Pixmap_scalePixels
668 */
669 bool scalePixels(const SkPixmap& dst, SkFilterQuality filterQuality) const;
670
671 /** Writes color to pixels bounded by subset; returns true on success.
672 Returns false if colorType() is kUnknown_SkColorType, or if subset does
673 not intersect bounds().
674
675 @param color unpremultiplied color to write
676 @param subset bounding integer SkRect of written pixels
677 @return true if pixels are changed
678
679 example: https://fiddle.skia.org/c/@Pixmap_erase
680 */
681 bool erase(SkColor color, const SkIRect& subset) const;
682
683 /** Writes color to pixels inside bounds(); returns true on success.
684 Returns false if colorType() is kUnknown_SkColorType, or if bounds()
685 is empty.
686
687 @param color unpremultiplied color to write
688 @return true if pixels are changed
689 */
690 bool erase(SkColor color) const { return this->erase(color, this->bounds()); }
691
692 /** Writes color to pixels bounded by subset; returns true on success.
693 if subset is nullptr, writes colors pixels inside bounds(). Returns false if
694 colorType() is kUnknown_SkColorType, if subset is not nullptr and does
695 not intersect bounds(), or if subset is nullptr and bounds() is empty.
696
697 @param color unpremultiplied color to write
698 @param subset bounding integer SkRect of pixels to write; may be nullptr
699 @return true if pixels are changed
700
701 example: https://fiddle.skia.org/c/@Pixmap_erase_3
702 */
703 bool erase(const SkColor4f& color, const SkIRect* subset = nullptr) const;
704
705private:
706 const void* fPixels;
707 size_t fRowBytes;
708 SkImageInfo fInfo;
709
710 friend class SkPixmapPriv;
711};
712
713#endif
714