1/*
2 * Copyright 2012 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 SkImage_DEFINED
9#define SkImage_DEFINED
10
11#include "include/core/SkAlphaType.h"
12#include "include/core/SkImageInfo.h"
13#include "include/core/SkRect.h"
14#include "include/core/SkRefCnt.h"
15#include "include/core/SkSize.h"
16#include "include/private/base/SkAPI.h"
17
18#include <cstddef>
19#include <cstdint>
20#include <memory>
21#include <optional>
22
23class GrDirectContext;
24class GrRecordingContext;
25class SkBitmap;
26class SkColorSpace;
27class SkData;
28class SkImage;
29class SkImageFilter;
30class SkImageGenerator;
31class SkMatrix;
32class SkMipmap;
33class SkPaint;
34class SkPicture;
35class SkPixmap;
36class SkShader;
37class SkSurfaceProps;
38enum SkColorType : int;
39enum class SkTextureCompressionType;
40enum class SkTileMode;
41
42struct SkIPoint;
43struct SkSamplingOptions;
44
45namespace skgpu::graphite { class Recorder; }
46
47namespace SkImages {
48
49/** Caller data passed to RasterReleaseProc; may be nullptr. */
50using ReleaseContext = void*;
51/** Function called when SkImage no longer shares pixels. ReleaseContext is
52 provided by caller when SkImage is created, and may be nullptr.
53*/
54using RasterReleaseProc = void(const void* pixels, ReleaseContext);
55
56/** Creates a CPU-backed SkImage from bitmap, sharing or copying bitmap pixels. If the bitmap
57 is marked immutable, and its pixel memory is shareable, it may be shared
58 instead of copied.
59
60 SkImage is returned if bitmap is valid. Valid SkBitmap parameters include:
61 dimensions are greater than zero;
62 each dimension fits in 29 bits;
63 SkColorType and SkAlphaType are valid, and SkColorType is not kUnknown_SkColorType;
64 row bytes are large enough to hold one row of pixels;
65 pixel address is not nullptr.
66
67 @param bitmap SkImageInfo, row bytes, and pixels
68 @return created SkImage, or nullptr
69*/
70SK_API sk_sp<SkImage> RasterFromBitmap(const SkBitmap& bitmap);
71
72/** Creates a CPU-backed SkImage from compressed data.
73
74 This method will decompress the compressed data and create an image wrapping
75 it. Any mipmap levels present in the compressed data are discarded.
76
77 @param data compressed data to store in SkImage
78 @param width width of full SkImage
79 @param height height of full SkImage
80 @param type type of compression used
81 @return created SkImage, or nullptr
82*/
83SK_API sk_sp<SkImage> RasterFromCompressedTextureData(sk_sp<SkData> data,
84 int width,
85 int height,
86 SkTextureCompressionType type);
87
88/**
89 * Return a SkImage using the encoded data, but attempts to defer decoding until the
90 * image is actually used/drawn. This deferral allows the system to cache the result, either on the
91 * CPU or on the GPU, depending on where the image is drawn. If memory is low, the cache may
92 * be purged, causing the next draw of the image to have to re-decode.
93 *
94 * If alphaType is nullopt, the image's alpha type will be chosen automatically based on the
95 * image format. Transparent images will default to kPremul_SkAlphaType. If alphaType contains
96 * kPremul_SkAlphaType or kUnpremul_SkAlphaType, that alpha type will be used. Forcing opaque
97 * (passing kOpaque_SkAlphaType) is not allowed, and will return nullptr.
98 *
99 * If the encoded format is not supported, nullptr is returned.
100 *
101 * @param encoded the encoded data
102 * @return created SkImage, or nullptr
103
104 example: https://fiddle.skia.org/c/@Image_DeferredFromEncodedData
105*/
106SK_API sk_sp<SkImage> DeferredFromEncodedData(sk_sp<SkData> encoded,
107 std::optional<SkAlphaType> alphaType = std::nullopt);
108
109/** Creates SkImage from data returned by imageGenerator. The image data will not be created
110 (on either the CPU or GPU) until the image is actually drawn.
111 Generated data is owned by SkImage and may not be shared or accessed.
112
113 SkImage is returned if generator data is valid. Valid data parameters vary by type of data
114 and platform.
115
116 imageGenerator may wrap SkPicture data, codec data, or custom data.
117
118 @param imageGenerator stock or custom routines to retrieve SkImage
119 @return created SkImage, or nullptr
120*/
121SK_API sk_sp<SkImage> DeferredFromGenerator(std::unique_ptr<SkImageGenerator> imageGenerator);
122
123enum class BitDepth {
124 kU8, //!< uses 8-bit unsigned int per color component
125 kF16, //!< uses 16-bit float per color component
126};
127
128/** Creates SkImage from picture. Returned SkImage width and height are set by dimensions.
129 SkImage draws picture with matrix and paint, set to bitDepth and colorSpace.
130
131 The Picture data is not turned into an image (CPU or GPU) until it is drawn.
132
133 If matrix is nullptr, draws with identity SkMatrix. If paint is nullptr, draws
134 with default SkPaint. colorSpace may be nullptr.
135
136 @param picture stream of drawing commands
137 @param dimensions width and height
138 @param matrix SkMatrix to rotate, scale, translate, and so on; may be nullptr
139 @param paint SkPaint to apply transparency, filtering, and so on; may be nullptr
140 @param bitDepth 8-bit integer or 16-bit float: per component
141 @param colorSpace range of colors; may be nullptr
142 @param props props to use when rasterizing the picture
143 @return created SkImage, or nullptr
144*/
145SK_API sk_sp<SkImage> DeferredFromPicture(sk_sp<SkPicture> picture,
146 const SkISize& dimensions,
147 const SkMatrix* matrix,
148 const SkPaint* paint,
149 BitDepth bitDepth,
150 sk_sp<SkColorSpace> colorSpace,
151 SkSurfaceProps props);
152SK_API sk_sp<SkImage> DeferredFromPicture(sk_sp<SkPicture> picture,
153 const SkISize& dimensions,
154 const SkMatrix* matrix,
155 const SkPaint* paint,
156 BitDepth bitDepth,
157 sk_sp<SkColorSpace> colorSpace);
158
159/** Creates a CPU-backed SkImage from pixmap, copying the pixel data.
160 As a result, pixmap pixels may be modified or deleted without affecting SkImage.
161
162 SkImage is returned if SkPixmap is valid. Valid SkPixmap parameters include:
163 dimensions are greater than zero;
164 each dimension fits in 29 bits;
165 SkColorType and SkAlphaType are valid, and SkColorType is not kUnknown_SkColorType;
166 row bytes are large enough to hold one row of pixels;
167 pixel address is not nullptr.
168
169 @param pixmap SkImageInfo, pixel address, and row bytes
170 @return copy of SkPixmap pixels, or nullptr
171
172 example: https://fiddle.skia.org/c/@Image_RasterFromPixmapCopy
173*/
174SK_API sk_sp<SkImage> RasterFromPixmapCopy(const SkPixmap& pixmap);
175
176/** Creates CPU-backed SkImage from pixmap, sharing SkPixmap pixels. Pixels must remain valid and
177 unchanged until rasterReleaseProc is called. rasterReleaseProc is passed
178 releaseContext when SkImage is deleted or no longer refers to pixmap pixels.
179
180 Pass nullptr for rasterReleaseProc to share SkPixmap without requiring a callback
181 when SkImage is released. Pass nullptr for releaseContext if rasterReleaseProc
182 does not require state.
183
184 SkImage is returned if pixmap is valid. Valid SkPixmap parameters include:
185 dimensions are greater than zero;
186 each dimension fits in 29 bits;
187 SkColorType and SkAlphaType are valid, and SkColorType is not kUnknown_SkColorType;
188 row bytes are large enough to hold one row of pixels;
189 pixel address is not nullptr.
190
191 @param pixmap SkImageInfo, pixel address, and row bytes
192 @param rasterReleaseProc function called when pixels can be released; or nullptr
193 @param releaseContext state passed to rasterReleaseProc; or nullptr
194 @return SkImage sharing pixmap
195*/
196SK_API sk_sp<SkImage> RasterFromPixmap(const SkPixmap& pixmap,
197 RasterReleaseProc rasterReleaseProc,
198 ReleaseContext releaseContext);
199
200/** Creates CPU-backed SkImage from pixel data described by info.
201 The pixels data will *not* be copied.
202
203 SkImage is returned if SkImageInfo is valid. Valid SkImageInfo parameters include:
204 dimensions are greater than zero;
205 each dimension fits in 29 bits;
206 SkColorType and SkAlphaType are valid, and SkColorType is not kUnknown_SkColorType;
207 rowBytes are large enough to hold one row of pixels;
208 pixels is not nullptr, and contains enough data for SkImage.
209
210 @param info contains width, height, SkAlphaType, SkColorType, SkColorSpace
211 @param pixels address or pixel storage
212 @param rowBytes size of pixel row or larger
213 @return SkImage sharing pixels, or nullptr
214*/
215SK_API sk_sp<SkImage> RasterFromData(const SkImageInfo& info,
216 sk_sp<SkData> pixels,
217 size_t rowBytes);
218
219} // namespace SkImages
220
221/** \class SkImage
222 SkImage describes a two dimensional array of pixels to draw. The pixels may be
223 decoded in a raster bitmap, encoded in a SkPicture or compressed data stream,
224 or located in GPU memory as a GPU texture.
225
226 SkImage cannot be modified after it is created. SkImage may allocate additional
227 storage as needed; for instance, an encoded SkImage may decode when drawn.
228
229 SkImage width and height are greater than zero. Creating an SkImage with zero width
230 or height returns SkImage equal to nullptr.
231
232 SkImage may be created from SkBitmap, SkPixmap, SkSurface, SkPicture, encoded streams,
233 GPU texture, YUV_ColorSpace data, or hardware buffer. Encoded streams supported
234 include BMP, GIF, HEIF, ICO, JPEG, PNG, WBMP, WebP. Supported encoding details
235 vary with platform.
236
237 See SkImages namespace for the static factory methods to make SkImages.
238
239 Clients should *not* subclass SkImage as there is a lot of internal machinery that is
240 not publicly accessible.
241*/
242class SK_API SkImage : public SkRefCnt {
243public:
244 /** Returns a SkImageInfo describing the width, height, color type, alpha type, and color space
245 of the SkImage.
246
247 @return image info of SkImage.
248 */
249 const SkImageInfo& imageInfo() const { return fInfo; }
250
251 /** Returns pixel count in each row.
252
253 @return pixel width in SkImage
254 */
255 int width() const { return fInfo.width(); }
256
257 /** Returns pixel row count.
258
259 @return pixel height in SkImage
260 */
261 int height() const { return fInfo.height(); }
262
263 /** Returns SkISize { width(), height() }.
264
265 @return integral size of width() and height()
266 */
267 SkISize dimensions() const { return SkISize::Make(w: fInfo.width(), h: fInfo.height()); }
268
269 /** Returns SkIRect { 0, 0, width(), height() }.
270
271 @return integral rectangle from origin to width() and height()
272 */
273 SkIRect bounds() const { return SkIRect::MakeWH(w: fInfo.width(), h: fInfo.height()); }
274
275 /** Returns value unique to image. SkImage contents cannot change after SkImage is
276 created. Any operation to create a new SkImage will receive generate a new
277 unique number.
278
279 @return unique identifier
280 */
281 uint32_t uniqueID() const { return fUniqueID; }
282
283 /** Returns SkAlphaType.
284
285 SkAlphaType returned was a parameter to an SkImage constructor,
286 or was parsed from encoded data.
287
288 @return SkAlphaType in SkImage
289
290 example: https://fiddle.skia.org/c/@Image_alphaType
291 */
292 SkAlphaType alphaType() const;
293
294 /** Returns SkColorType if known; otherwise, returns kUnknown_SkColorType.
295
296 @return SkColorType of SkImage
297
298 example: https://fiddle.skia.org/c/@Image_colorType
299 */
300 SkColorType colorType() const;
301
302 /** Returns SkColorSpace, the range of colors, associated with SkImage. The
303 reference count of SkColorSpace is unchanged. The returned SkColorSpace is
304 immutable.
305
306 SkColorSpace returned was passed to an SkImage constructor,
307 or was parsed from encoded data. SkColorSpace returned may be ignored when SkImage
308 is drawn, depending on the capabilities of the SkSurface receiving the drawing.
309
310 @return SkColorSpace in SkImage, or nullptr
311
312 example: https://fiddle.skia.org/c/@Image_colorSpace
313 */
314 SkColorSpace* colorSpace() const;
315
316 /** Returns a smart pointer to SkColorSpace, the range of colors, associated with
317 SkImage. The smart pointer tracks the number of objects sharing this
318 SkColorSpace reference so the memory is released when the owners destruct.
319
320 The returned SkColorSpace is immutable.
321
322 SkColorSpace returned was passed to an SkImage constructor,
323 or was parsed from encoded data. SkColorSpace returned may be ignored when SkImage
324 is drawn, depending on the capabilities of the SkSurface receiving the drawing.
325
326 @return SkColorSpace in SkImage, or nullptr, wrapped in a smart pointer
327
328 example: https://fiddle.skia.org/c/@Image_refColorSpace
329 */
330 sk_sp<SkColorSpace> refColorSpace() const;
331
332 /** Returns true if SkImage pixels represent transparency only. If true, each pixel
333 is packed in 8 bits as defined by kAlpha_8_SkColorType.
334
335 @return true if pixels represent a transparency mask
336
337 example: https://fiddle.skia.org/c/@Image_isAlphaOnly
338 */
339 bool isAlphaOnly() const;
340
341 /** Returns true if pixels ignore their alpha value and are treated as fully opaque.
342
343 @return true if SkAlphaType is kOpaque_SkAlphaType
344 */
345 bool isOpaque() const { return SkAlphaTypeIsOpaque(at: this->alphaType()); }
346
347 /**
348 * Make a shader with the specified tiling and mipmap sampling.
349 */
350 sk_sp<SkShader> makeShader(SkTileMode tmx, SkTileMode tmy, const SkSamplingOptions&,
351 const SkMatrix* localMatrix = nullptr) const;
352 sk_sp<SkShader> makeShader(SkTileMode tmx, SkTileMode tmy, const SkSamplingOptions& sampling,
353 const SkMatrix& lm) const;
354 /** Defaults to clamp in both X and Y. */
355 sk_sp<SkShader> makeShader(const SkSamplingOptions& sampling, const SkMatrix& lm) const;
356 sk_sp<SkShader> makeShader(const SkSamplingOptions& sampling,
357 const SkMatrix* lm = nullptr) const;
358
359 /**
360 * makeRawShader functions like makeShader, but for images that contain non-color data.
361 * This includes images encoding things like normals, material properties (eg, roughness),
362 * heightmaps, or any other purely mathematical data that happens to be stored in an image.
363 * These types of images are useful with some programmable shaders (see: SkRuntimeEffect).
364 *
365 * Raw image shaders work like regular image shaders (including filtering and tiling), with
366 * a few major differences:
367 * - No color space transformation is ever applied (the color space of the image is ignored).
368 * - Images with an alpha type of kUnpremul are *not* automatically premultiplied.
369 * - Bicubic filtering is not supported. If SkSamplingOptions::useCubic is true, these
370 * factories will return nullptr.
371 */
372 sk_sp<SkShader> makeRawShader(SkTileMode tmx, SkTileMode tmy, const SkSamplingOptions&,
373 const SkMatrix* localMatrix = nullptr) const;
374 sk_sp<SkShader> makeRawShader(SkTileMode tmx, SkTileMode tmy, const SkSamplingOptions& sampling,
375 const SkMatrix& lm) const;
376 /** Defaults to clamp in both X and Y. */
377 sk_sp<SkShader> makeRawShader(const SkSamplingOptions& sampling, const SkMatrix& lm) const;
378 sk_sp<SkShader> makeRawShader(const SkSamplingOptions& sampling,
379 const SkMatrix* lm = nullptr) const;
380
381 /** Copies SkImage pixel address, row bytes, and SkImageInfo to pixmap, if address
382 is available, and returns true. If pixel address is not available, return
383 false and leave pixmap unchanged.
384
385 @param pixmap storage for pixel state if pixels are readable; otherwise, ignored
386 @return true if SkImage has direct access to pixels
387
388 example: https://fiddle.skia.org/c/@Image_peekPixels
389 */
390 bool peekPixels(SkPixmap* pixmap) const;
391
392 /** Returns true if the contents of SkImage was created on or uploaded to GPU memory,
393 and is available as a GPU texture.
394
395 @return true if SkImage is a GPU texture
396
397 example: https://fiddle.skia.org/c/@Image_isTextureBacked
398 */
399 virtual bool isTextureBacked() const = 0;
400
401 /** Returns an approximation of the amount of texture memory used by the image. Returns
402 zero if the image is not texture backed or if the texture has an external format.
403 */
404 virtual size_t textureSize() const = 0;
405
406 /** Returns true if SkImage can be drawn on either raster surface or GPU surface.
407 If context is nullptr, tests if SkImage draws on raster surface;
408 otherwise, tests if SkImage draws on GPU surface associated with context.
409
410 SkImage backed by GPU texture may become invalid if associated context is
411 invalid. lazy image may be invalid and may not draw to raster surface or
412 GPU surface or both.
413
414 @param context GPU context
415 @return true if SkImage can be drawn
416
417 example: https://fiddle.skia.org/c/@Image_isValid
418 */
419 virtual bool isValid(GrRecordingContext* context) const = 0;
420
421 /** \enum SkImage::CachingHint
422 CachingHint selects whether Skia may internally cache SkBitmap generated by
423 decoding SkImage, or by copying SkImage from GPU to CPU. The default behavior
424 allows caching SkBitmap.
425
426 Choose kDisallow_CachingHint if SkImage pixels are to be used only once, or
427 if SkImage pixels reside in a cache outside of Skia, or to reduce memory pressure.
428
429 Choosing kAllow_CachingHint does not ensure that pixels will be cached.
430 SkImage pixels may not be cached if memory requirements are too large or
431 pixels are not accessible.
432 */
433 enum CachingHint {
434 kAllow_CachingHint, //!< allows internally caching decoded and copied pixels
435 kDisallow_CachingHint, //!< disallows internally caching decoded and copied pixels
436 };
437
438 /** Copies SkRect of pixels from SkImage to dstPixels. Copy starts at offset (srcX, srcY),
439 and does not exceed SkImage (width(), height()).
440
441 dstInfo specifies width, height, SkColorType, SkAlphaType, and SkColorSpace of
442 destination. dstRowBytes specifies the gap from one destination row to the next.
443 Returns true if pixels are copied. Returns false if:
444 - dstInfo.addr() equals nullptr
445 - dstRowBytes is less than dstInfo.minRowBytes()
446 - SkPixelRef is nullptr
447
448 Pixels are copied only if pixel conversion is possible. If SkImage SkColorType is
449 kGray_8_SkColorType, or kAlpha_8_SkColorType; dstInfo.colorType() must match.
450 If SkImage SkColorType is kGray_8_SkColorType, dstInfo.colorSpace() must match.
451 If SkImage SkAlphaType is kOpaque_SkAlphaType, dstInfo.alphaType() must
452 match. If SkImage SkColorSpace is nullptr, dstInfo.colorSpace() must match. Returns
453 false if pixel conversion is not possible.
454
455 srcX and srcY may be negative to copy only top or left of source. Returns
456 false if width() or height() is zero or negative.
457 Returns false if abs(srcX) >= Image width(), or if abs(srcY) >= Image height().
458
459 If cachingHint is kAllow_CachingHint, pixels may be retained locally.
460 If cachingHint is kDisallow_CachingHint, pixels are not added to the local cache.
461
462 @param context the GrDirectContext in play, if it exists
463 @param dstInfo destination width, height, SkColorType, SkAlphaType, SkColorSpace
464 @param dstPixels destination pixel storage
465 @param dstRowBytes destination row length
466 @param srcX column index whose absolute value is less than width()
467 @param srcY row index whose absolute value is less than height()
468 @param cachingHint whether the pixels should be cached locally
469 @return true if pixels are copied to dstPixels
470 */
471 bool readPixels(GrDirectContext* context,
472 const SkImageInfo& dstInfo,
473 void* dstPixels,
474 size_t dstRowBytes,
475 int srcX, int srcY,
476 CachingHint cachingHint = kAllow_CachingHint) const;
477
478 /** Copies a SkRect of pixels from SkImage to dst. Copy starts at (srcX, srcY), and
479 does not exceed SkImage (width(), height()).
480
481 dst specifies width, height, SkColorType, SkAlphaType, SkColorSpace, pixel storage,
482 and row bytes of destination. dst.rowBytes() specifics the gap from one destination
483 row to the next. Returns true if pixels are copied. Returns false if:
484 - dst pixel storage equals nullptr
485 - dst.rowBytes is less than SkImageInfo::minRowBytes
486 - SkPixelRef is nullptr
487
488 Pixels are copied only if pixel conversion is possible. If SkImage SkColorType is
489 kGray_8_SkColorType, or kAlpha_8_SkColorType; dst.colorType() must match.
490 If SkImage SkColorType is kGray_8_SkColorType, dst.colorSpace() must match.
491 If SkImage SkAlphaType is kOpaque_SkAlphaType, dst.alphaType() must
492 match. If SkImage SkColorSpace is nullptr, dst.colorSpace() must match. Returns
493 false if pixel conversion is not possible.
494
495 srcX and srcY may be negative to copy only top or left of source. Returns
496 false if width() or height() is zero or negative.
497 Returns false if abs(srcX) >= Image width(), or if abs(srcY) >= Image height().
498
499 If cachingHint is kAllow_CachingHint, pixels may be retained locally.
500 If cachingHint is kDisallow_CachingHint, pixels are not added to the local cache.
501
502 @param context the GrDirectContext in play, if it exists
503 @param dst destination SkPixmap: SkImageInfo, pixels, row bytes
504 @param srcX column index whose absolute value is less than width()
505 @param srcY row index whose absolute value is less than height()
506 @param cachingHint whether the pixels should be cached locallyZ
507 @return true if pixels are copied to dst
508 */
509 bool readPixels(GrDirectContext* context,
510 const SkPixmap& dst,
511 int srcX,
512 int srcY,
513 CachingHint cachingHint = kAllow_CachingHint) const;
514
515#ifndef SK_IMAGE_READ_PIXELS_DISABLE_LEGACY_API
516 /** Deprecated. Use the variants that accept a GrDirectContext. */
517 bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes,
518 int srcX, int srcY, CachingHint cachingHint = kAllow_CachingHint) const;
519 bool readPixels(const SkPixmap& dst, int srcX, int srcY,
520 CachingHint cachingHint = kAllow_CachingHint) const;
521#endif
522
523 /** The result from asyncRescaleAndReadPixels() or asyncRescaleAndReadPixelsYUV420(). */
524 class AsyncReadResult {
525 public:
526 AsyncReadResult(const AsyncReadResult&) = delete;
527 AsyncReadResult(AsyncReadResult&&) = delete;
528 AsyncReadResult& operator=(const AsyncReadResult&) = delete;
529 AsyncReadResult& operator=(AsyncReadResult&&) = delete;
530
531 virtual ~AsyncReadResult() = default;
532 virtual int count() const = 0;
533 virtual const void* data(int i) const = 0;
534 virtual size_t rowBytes(int i) const = 0;
535
536 protected:
537 AsyncReadResult() = default;
538 };
539
540 /** Client-provided context that is passed to client-provided ReadPixelsContext. */
541 using ReadPixelsContext = void*;
542
543 /** Client-provided callback to asyncRescaleAndReadPixels() or
544 asyncRescaleAndReadPixelsYUV420() that is called when read result is ready or on failure.
545 */
546 using ReadPixelsCallback = void(ReadPixelsContext, std::unique_ptr<const AsyncReadResult>);
547
548 enum class RescaleGamma : bool { kSrc, kLinear };
549
550 enum class RescaleMode {
551 kNearest,
552 kLinear,
553 kRepeatedLinear,
554 kRepeatedCubic,
555 };
556
557 /** Makes image pixel data available to caller, possibly asynchronously. It can also rescale
558 the image pixels.
559
560 Currently asynchronous reads are only supported on the GPU backend and only when the
561 underlying 3D API supports transfer buffers and CPU/GPU synchronization primitives. In all
562 other cases this operates synchronously.
563
564 Data is read from the source sub-rectangle, is optionally converted to a linear gamma, is
565 rescaled to the size indicated by 'info', is then converted to the color space, color type,
566 and alpha type of 'info'. A 'srcRect' that is not contained by the bounds of the image
567 causes failure.
568
569 When the pixel data is ready the caller's ReadPixelsCallback is called with a
570 AsyncReadResult containing pixel data in the requested color type, alpha type, and color
571 space. The AsyncReadResult will have count() == 1. Upon failure the callback is called with
572 nullptr for AsyncReadResult. For a GPU image this flushes work but a submit must occur to
573 guarantee a finite time before the callback is called.
574
575 The data is valid for the lifetime of AsyncReadResult with the exception that if the SkImage
576 is GPU-backed the data is immediately invalidated if the context is abandoned or
577 destroyed.
578
579 @param info info of the requested pixels
580 @param srcRect subrectangle of image to read
581 @param rescaleGamma controls whether rescaling is done in the image's gamma or whether
582 the source data is transformed to a linear gamma before rescaling.
583 @param rescaleMode controls the technique (and cost) of the rescaling
584 @param callback function to call with result of the read
585 @param context passed to callback
586 */
587 void asyncRescaleAndReadPixels(const SkImageInfo& info,
588 const SkIRect& srcRect,
589 RescaleGamma rescaleGamma,
590 RescaleMode rescaleMode,
591 ReadPixelsCallback callback,
592 ReadPixelsContext context) const;
593
594 /**
595 Similar to asyncRescaleAndReadPixels but performs an additional conversion to YUV. The
596 RGB->YUV conversion is controlled by 'yuvColorSpace'. The YUV data is returned as three
597 planes ordered y, u, v. The u and v planes are half the width and height of the resized
598 rectangle. The y, u, and v values are single bytes. Currently this fails if 'dstSize'
599 width and height are not even. A 'srcRect' that is not contained by the bounds of the
600 image causes failure.
601
602 When the pixel data is ready the caller's ReadPixelsCallback is called with a
603 AsyncReadResult containing the planar data. The AsyncReadResult will have count() == 3.
604 Upon failure the callback is called with nullptr for AsyncReadResult. For a GPU image this
605 flushes work but a submit must occur to guarantee a finite time before the callback is
606 called.
607
608 The data is valid for the lifetime of AsyncReadResult with the exception that if the SkImage
609 is GPU-backed the data is immediately invalidated if the context is abandoned or
610 destroyed.
611
612 @param yuvColorSpace The transformation from RGB to YUV. Applied to the resized image
613 after it is converted to dstColorSpace.
614 @param dstColorSpace The color space to convert the resized image to, after rescaling.
615 @param srcRect The portion of the image to rescale and convert to YUV planes.
616 @param dstSize The size to rescale srcRect to
617 @param rescaleGamma controls whether rescaling is done in the image's gamma or whether
618 the source data is transformed to a linear gamma before rescaling.
619 @param rescaleMode controls the technique (and cost) of the rescaling
620 @param callback function to call with the planar read result
621 @param context passed to callback
622 */
623 void asyncRescaleAndReadPixelsYUV420(SkYUVColorSpace yuvColorSpace,
624 sk_sp<SkColorSpace> dstColorSpace,
625 const SkIRect& srcRect,
626 const SkISize& dstSize,
627 RescaleGamma rescaleGamma,
628 RescaleMode rescaleMode,
629 ReadPixelsCallback callback,
630 ReadPixelsContext context) const;
631
632 /**
633 * Identical to asyncRescaleAndReadPixelsYUV420 but a fourth plane is returned in the
634 * AsyncReadResult passed to 'callback'. The fourth plane contains the alpha chanel at the
635 * same full resolution as the Y plane.
636 */
637 void asyncRescaleAndReadPixelsYUVA420(SkYUVColorSpace yuvColorSpace,
638 sk_sp<SkColorSpace> dstColorSpace,
639 const SkIRect& srcRect,
640 const SkISize& dstSize,
641 RescaleGamma rescaleGamma,
642 RescaleMode rescaleMode,
643 ReadPixelsCallback callback,
644 ReadPixelsContext context) const;
645
646 /** Copies SkImage to dst, scaling pixels to fit dst.width() and dst.height(), and
647 converting pixels to match dst.colorType() and dst.alphaType(). Returns true if
648 pixels are copied. Returns false if dst.addr() is nullptr, or dst.rowBytes() is
649 less than dst SkImageInfo::minRowBytes.
650
651 Pixels are copied only if pixel conversion is possible. If SkImage SkColorType is
652 kGray_8_SkColorType, or kAlpha_8_SkColorType; dst.colorType() must match.
653 If SkImage SkColorType is kGray_8_SkColorType, dst.colorSpace() must match.
654 If SkImage SkAlphaType is kOpaque_SkAlphaType, dst.alphaType() must
655 match. If SkImage SkColorSpace is nullptr, dst.colorSpace() must match. Returns
656 false if pixel conversion is not possible.
657
658 If cachingHint is kAllow_CachingHint, pixels may be retained locally.
659 If cachingHint is kDisallow_CachingHint, pixels are not added to the local cache.
660
661 @param dst destination SkPixmap: SkImageInfo, pixels, row bytes
662 @return true if pixels are scaled to fit dst
663 */
664 bool scalePixels(const SkPixmap& dst, const SkSamplingOptions&,
665 CachingHint cachingHint = kAllow_CachingHint) const;
666
667 /** Returns encoded SkImage pixels as SkData, if SkImage was created from supported
668 encoded stream format. Platform support for formats vary and may require building
669 with one or more of: SK_ENCODE_JPEG, SK_ENCODE_PNG, SK_ENCODE_WEBP.
670
671 Returns nullptr if SkImage contents are not encoded.
672
673 @return encoded SkImage, or nullptr
674
675 example: https://fiddle.skia.org/c/@Image_refEncodedData
676 */
677 sk_sp<SkData> refEncodedData() const;
678
679 /** Returns subset of this image.
680
681 Returns nullptr if any of the following are true:
682 - Subset is empty
683 - Subset is not contained inside the image's bounds
684 - Pixels in the source image could not be read or copied
685 - This image is texture-backed and the provided context is null or does not match
686 the source image's context.
687
688 If the source image was texture-backed, the resulting image will be texture-backed also.
689 Otherwise, the returned image will be raster-backed.
690
691 @param direct the GrDirectContext of the source image (nullptr is ok if the source image
692 is not texture-backed).
693 @param subset bounds of returned SkImage
694 @return the subsetted image, or nullptr
695
696 example: https://fiddle.skia.org/c/@Image_makeSubset
697 */
698 virtual sk_sp<SkImage> makeSubset(GrDirectContext* direct, const SkIRect& subset) const = 0;
699
700 struct RequiredProperties {
701 bool fMipmapped;
702 };
703
704 /** Returns subset of this image.
705
706 Returns nullptr if any of the following are true:
707 - Subset is empty
708 - Subset is not contained inside the image's bounds
709 - Pixels in the image could not be read or copied
710 - This image is texture-backed and the provided context is null or does not match
711 the source image's context.
712
713 If the source image was texture-backed, the resulting image will be texture-backed also.
714 Otherwise, the returned image will be raster-backed.
715
716 @param recorder the recorder of the source image (nullptr is ok if the
717 source image was texture-backed).
718 @param subset bounds of returned SkImage
719 @param RequiredProperties properties the returned SkImage must possess (e.g. mipmaps)
720 @return the subsetted image, or nullptr
721 */
722 virtual sk_sp<SkImage> makeSubset(skgpu::graphite::Recorder*,
723 const SkIRect& subset,
724 RequiredProperties) const = 0;
725
726 /**
727 * Returns true if the image has mipmap levels.
728 */
729 bool hasMipmaps() const;
730
731 /**
732 * Returns an image with the same "base" pixels as the this image, but with mipmap levels
733 * automatically generated and attached.
734 */
735 sk_sp<SkImage> withDefaultMipmaps() const;
736
737 /** Returns raster image or lazy image. Copies SkImage backed by GPU texture into
738 CPU memory if needed. Returns original SkImage if decoded in raster bitmap,
739 or if encoded in a stream.
740
741 Returns nullptr if backed by GPU texture and copy fails.
742
743 @return raster image, lazy image, or nullptr
744
745 example: https://fiddle.skia.org/c/@Image_makeNonTextureImage
746 */
747 sk_sp<SkImage> makeNonTextureImage(GrDirectContext* = nullptr) const;
748
749 /** Returns raster image. Copies SkImage backed by GPU texture into CPU memory,
750 or decodes SkImage from lazy image. Returns original SkImage if decoded in
751 raster bitmap.
752
753 Returns nullptr if copy, decode, or pixel read fails.
754
755 If cachingHint is kAllow_CachingHint, pixels may be retained locally.
756 If cachingHint is kDisallow_CachingHint, pixels are not added to the local cache.
757
758 @return raster image, or nullptr
759
760 example: https://fiddle.skia.org/c/@Image_makeRasterImage
761 */
762 sk_sp<SkImage> makeRasterImage(GrDirectContext*,
763 CachingHint cachingHint = kDisallow_CachingHint) const;
764
765#if !defined(SK_IMAGE_READ_PIXELS_DISABLE_LEGACY_API)
766 sk_sp<SkImage> makeRasterImage(CachingHint cachingHint = kDisallow_CachingHint) const {
767 return this->makeRasterImage(nullptr, cachingHint);
768 }
769#endif
770
771 /** Creates filtered SkImage. filter processes original SkImage, potentially changing
772 color, position, and size. subset is the bounds of original SkImage processed
773 by filter. clipBounds is the expected bounds of the filtered SkImage. outSubset
774 is required storage for the actual bounds of the filtered SkImage. offset is
775 required storage for translation of returned SkImage.
776
777 Returns nullptr if SkImage could not be created or if the recording context provided doesn't
778 match the GPU context in which the image was created. If nullptr is returned, outSubset
779 and offset are undefined.
780
781 Useful for animation of SkImageFilter that varies size from frame to frame.
782 Returned SkImage is created larger than required by filter so that GPU texture
783 can be reused with different sized effects. outSubset describes the valid bounds
784 of GPU texture returned. offset translates the returned SkImage to keep subsequent
785 animation frames aligned with respect to each other.
786
787 @param context the GrRecordingContext in play - if it exists
788 @param filter how SkImage is sampled when transformed
789 @param subset bounds of SkImage processed by filter
790 @param clipBounds expected bounds of filtered SkImage
791 @param outSubset storage for returned SkImage bounds
792 @param offset storage for returned SkImage translation
793 @return filtered SkImage, or nullptr
794 */
795 sk_sp<SkImage> makeWithFilter(GrRecordingContext* context,
796 const SkImageFilter* filter,
797 const SkIRect& subset,
798 const SkIRect& clipBounds,
799 SkIRect* outSubset,
800 SkIPoint* offset) const;
801
802 /** Deprecated.
803 */
804 enum LegacyBitmapMode {
805 kRO_LegacyBitmapMode, //!< returned bitmap is read-only and immutable
806 };
807
808 /** Deprecated.
809 Creates raster SkBitmap with same pixels as SkImage. If legacyBitmapMode is
810 kRO_LegacyBitmapMode, returned bitmap is read-only and immutable.
811 Returns true if SkBitmap is stored in bitmap. Returns false and resets bitmap if
812 SkBitmap write did not succeed.
813
814 @param bitmap storage for legacy SkBitmap
815 @param legacyBitmapMode bitmap is read-only and immutable
816 @return true if SkBitmap was created
817 */
818 bool asLegacyBitmap(SkBitmap* bitmap,
819 LegacyBitmapMode legacyBitmapMode = kRO_LegacyBitmapMode) const;
820
821 /** Returns true if SkImage is backed by an image-generator or other service that creates
822 and caches its pixels or texture on-demand.
823
824 @return true if SkImage is created as needed
825
826 example: https://fiddle.skia.org/c/@Image_isLazyGenerated_a
827 example: https://fiddle.skia.org/c/@Image_isLazyGenerated_b
828 */
829 virtual bool isLazyGenerated() const = 0;
830
831 /** Creates SkImage in target SkColorSpace.
832 Returns nullptr if SkImage could not be created.
833
834 Returns original SkImage if it is in target SkColorSpace.
835 Otherwise, converts pixels from SkImage SkColorSpace to target SkColorSpace.
836 If SkImage colorSpace() returns nullptr, SkImage SkColorSpace is assumed to be sRGB.
837
838 If this image is texture-backed, the context parameter is required and must match the
839 context of the source image.
840
841 @param direct The GrDirectContext in play, if it exists
842 @param target SkColorSpace describing color range of returned SkImage
843 @return created SkImage in target SkColorSpace
844
845 example: https://fiddle.skia.org/c/@Image_makeColorSpace
846 */
847 virtual sk_sp<SkImage> makeColorSpace(GrDirectContext* direct,
848 sk_sp<SkColorSpace> target) const = 0;
849
850 /** Creates SkImage in target SkColorSpace.
851 Returns nullptr if SkImage could not be created.
852
853 Returns original SkImage if it is in target SkColorSpace.
854 Otherwise, converts pixels from SkImage SkColorSpace to target SkColorSpace.
855 If SkImage colorSpace() returns nullptr, SkImage SkColorSpace is assumed to be sRGB.
856
857 If this image is graphite-backed, the recorder parameter is required.
858
859 @param targetColorSpace SkColorSpace describing color range of returned SkImage
860 @param recorder The Recorder in which to create the new image
861 @param RequiredProperties properties the returned SkImage must possess (e.g. mipmaps)
862 @return created SkImage in target SkColorSpace
863 */
864 virtual sk_sp<SkImage> makeColorSpace(skgpu::graphite::Recorder*,
865 sk_sp<SkColorSpace> targetColorSpace,
866 RequiredProperties) const = 0;
867
868 /** Experimental.
869 Creates SkImage in target SkColorType and SkColorSpace.
870 Returns nullptr if SkImage could not be created.
871
872 Returns original SkImage if it is in target SkColorType and SkColorSpace.
873
874 If this image is texture-backed, the context parameter is required and must match the
875 context of the source image.
876
877 @param direct The GrDirectContext in play, if it exists
878 @param targetColorType SkColorType of returned SkImage
879 @param targetColorSpace SkColorSpace of returned SkImage
880 @return created SkImage in target SkColorType and SkColorSpace
881 */
882 virtual sk_sp<SkImage> makeColorTypeAndColorSpace(GrDirectContext* direct,
883 SkColorType targetColorType,
884 sk_sp<SkColorSpace> targetCS) const = 0;
885
886 /** Experimental.
887 Creates SkImage in target SkColorType and SkColorSpace.
888 Returns nullptr if SkImage could not be created.
889
890 Returns original SkImage if it is in target SkColorType and SkColorSpace.
891
892 If this image is graphite-backed, the recorder parameter is required.
893
894 @param targetColorType SkColorType of returned SkImage
895 @param targetColorSpace SkColorSpace of returned SkImage
896 @param recorder The Recorder in which to create the new image
897 @param RequiredProperties properties the returned SkImage must possess (e.g. mipmaps)
898 @return created SkImage in target SkColorType and SkColorSpace
899 */
900 virtual sk_sp<SkImage> makeColorTypeAndColorSpace(skgpu::graphite::Recorder*,
901 SkColorType targetColorType,
902 sk_sp<SkColorSpace> targetColorSpace,
903 RequiredProperties) const = 0;
904
905 /** Creates a new SkImage identical to this one, but with a different SkColorSpace.
906 This does not convert the underlying pixel data, so the resulting image will draw
907 differently.
908 */
909 sk_sp<SkImage> reinterpretColorSpace(sk_sp<SkColorSpace> newColorSpace) const;
910
911private:
912 SkImage(const SkImageInfo& info, uint32_t uniqueID);
913
914 friend class SkBitmap;
915 friend class SkImage_Base; // for private ctor
916 friend class SkImage_Raster; // for withMipmaps
917 friend class SkMipmapBuilder;
918
919 SkImageInfo fInfo;
920 const uint32_t fUniqueID;
921
922 sk_sp<SkImage> withMipmaps(sk_sp<SkMipmap>) const;
923
924 using INHERITED = SkRefCnt;
925};
926
927#endif
928

source code of flutter_engine/third_party/skia/include/core/SkImage.h