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 | |
23 | class GrDirectContext; |
24 | class GrRecordingContext; |
25 | class SkBitmap; |
26 | class SkColorSpace; |
27 | class SkData; |
28 | class SkImage; |
29 | class SkImageFilter; |
30 | class SkImageGenerator; |
31 | class SkMatrix; |
32 | class SkMipmap; |
33 | class SkPaint; |
34 | class SkPicture; |
35 | class SkPixmap; |
36 | class SkShader; |
37 | class SkSurfaceProps; |
38 | enum SkColorType : int; |
39 | enum class SkTextureCompressionType; |
40 | enum class SkTileMode; |
41 | |
42 | struct SkIPoint; |
43 | struct SkSamplingOptions; |
44 | |
45 | namespace skgpu::graphite { class Recorder; } |
46 | |
47 | namespace SkImages { |
48 | |
49 | /** Caller data passed to RasterReleaseProc; may be nullptr. */ |
50 | using 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 | */ |
54 | using 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 | */ |
70 | SK_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 | */ |
83 | SK_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 | */ |
106 | SK_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 | */ |
121 | SK_API sk_sp<SkImage> DeferredFromGenerator(std::unique_ptr<SkImageGenerator> imageGenerator); |
122 | |
123 | enum 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 | */ |
145 | SK_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); |
152 | SK_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 | */ |
174 | SK_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 | */ |
196 | SK_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 | */ |
215 | SK_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 | */ |
242 | class SK_API SkImage : public SkRefCnt { |
243 | public: |
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 | |
911 | private: |
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 | |