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/SkFilterQuality.h"
12#include "include/core/SkImageEncoder.h"
13#include "include/core/SkImageInfo.h"
14#include "include/core/SkRefCnt.h"
15#include "include/core/SkScalar.h"
16#include "include/core/SkShader.h"
17#include "include/core/SkTileMode.h"
18#include "include/gpu/GrTypes.h"
19#include <functional> // std::function
20
21#if defined(SK_BUILD_FOR_ANDROID) && __ANDROID_API__ >= 26
22#include <android/hardware_buffer.h>
23#endif
24
25class SkData;
26class SkCanvas;
27class SkImageFilter;
28class SkImageGenerator;
29class SkPaint;
30class SkPicture;
31class SkSurface;
32class GrBackendTexture;
33class GrContext;
34class GrContextThreadSafeProxy;
35
36struct SkYUVAIndex;
37
38/** \class SkImage
39 SkImage describes a two dimensional array of pixels to draw. The pixels may be
40 decoded in a raster bitmap, encoded in a SkPicture or compressed data stream,
41 or located in GPU memory as a GPU texture.
42
43 SkImage cannot be modified after it is created. SkImage may allocate additional
44 storage as needed; for instance, an encoded SkImage may decode when drawn.
45
46 SkImage width and height are greater than zero. Creating an SkImage with zero width
47 or height returns SkImage equal to nullptr.
48
49 SkImage may be created from SkBitmap, SkPixmap, SkSurface, SkPicture, encoded streams,
50 GPU texture, YUV_ColorSpace data, or hardware buffer. Encoded streams supported
51 include BMP, GIF, HEIF, ICO, JPEG, PNG, WBMP, WebP. Supported encoding details
52 vary with platform.
53*/
54class SK_API SkImage : public SkRefCnt {
55public:
56
57 /** Caller data passed to RasterReleaseProc; may be nullptr.
58 */
59 typedef void* ReleaseContext;
60
61 /** Creates SkImage from SkPixmap and copy of pixels. Since pixels are copied, SkPixmap
62 pixels may be modified or deleted without affecting SkImage.
63
64 SkImage is returned if SkPixmap is valid. Valid SkPixmap parameters include:
65 dimensions are greater than zero;
66 each dimension fits in 29 bits;
67 SkColorType and SkAlphaType are valid, and SkColorType is not kUnknown_SkColorType;
68 row bytes are large enough to hold one row of pixels;
69 pixel address is not nullptr.
70
71 @param pixmap SkImageInfo, pixel address, and row bytes
72 @return copy of SkPixmap pixels, or nullptr
73
74 example: https://fiddle.skia.org/c/@Image_MakeRasterCopy
75 */
76 static sk_sp<SkImage> MakeRasterCopy(const SkPixmap& pixmap);
77
78 /** Creates SkImage from SkImageInfo, sharing pixels.
79
80 SkImage is returned if SkImageInfo is valid. Valid SkImageInfo parameters include:
81 dimensions are greater than zero;
82 each dimension fits in 29 bits;
83 SkColorType and SkAlphaType are valid, and SkColorType is not kUnknown_SkColorType;
84 rowBytes are large enough to hold one row of pixels;
85 pixels is not nullptr, and contains enough data for SkImage.
86
87 @param info contains width, height, SkAlphaType, SkColorType, SkColorSpace
88 @param pixels address or pixel storage
89 @param rowBytes size of pixel row or larger
90 @return SkImage sharing pixels, or nullptr
91 */
92 static sk_sp<SkImage> MakeRasterData(const SkImageInfo& info, sk_sp<SkData> pixels,
93 size_t rowBytes);
94
95 /** Function called when SkImage no longer shares pixels. ReleaseContext is
96 provided by caller when SkImage is created, and may be nullptr.
97 */
98 typedef void (*RasterReleaseProc)(const void* pixels, ReleaseContext);
99
100 /** Creates SkImage from pixmap, sharing SkPixmap pixels. Pixels must remain valid and
101 unchanged until rasterReleaseProc is called. rasterReleaseProc is passed
102 releaseContext when SkImage is deleted or no longer refers to pixmap pixels.
103
104 Pass nullptr for rasterReleaseProc to share SkPixmap without requiring a callback
105 when SkImage is released. Pass nullptr for releaseContext if rasterReleaseProc
106 does not require state.
107
108 SkImage is returned if pixmap is valid. Valid SkPixmap parameters include:
109 dimensions are greater than zero;
110 each dimension fits in 29 bits;
111 SkColorType and SkAlphaType are valid, and SkColorType is not kUnknown_SkColorType;
112 row bytes are large enough to hold one row of pixels;
113 pixel address is not nullptr.
114
115 @param pixmap SkImageInfo, pixel address, and row bytes
116 @param rasterReleaseProc function called when pixels can be released; or nullptr
117 @param releaseContext state passed to rasterReleaseProc; or nullptr
118 @return SkImage sharing pixmap
119 */
120 static sk_sp<SkImage> MakeFromRaster(const SkPixmap& pixmap,
121 RasterReleaseProc rasterReleaseProc,
122 ReleaseContext releaseContext);
123
124 /** Creates SkImage from bitmap, sharing or copying bitmap pixels. If the bitmap
125 is marked immutable, and its pixel memory is shareable, it may be shared
126 instead of copied.
127
128 SkImage is returned if bitmap is valid. Valid SkBitmap parameters include:
129 dimensions are greater than zero;
130 each dimension fits in 29 bits;
131 SkColorType and SkAlphaType are valid, and SkColorType is not kUnknown_SkColorType;
132 row bytes are large enough to hold one row of pixels;
133 pixel address is not nullptr.
134
135 @param bitmap SkImageInfo, row bytes, and pixels
136 @return created SkImage, or nullptr
137
138 example: https://fiddle.skia.org/c/@Image_MakeFromBitmap
139 */
140 static sk_sp<SkImage> MakeFromBitmap(const SkBitmap& bitmap);
141
142 /** Creates SkImage from data returned by imageGenerator. Generated data is owned by SkImage and
143 may not be shared or accessed.
144
145 subset allows selecting a portion of the full image. Pass nullptr to select the entire
146 image; otherwise, subset must be contained by image bounds.
147
148 SkImage is returned if generator data is valid. Valid data parameters vary by type of data
149 and platform.
150
151 imageGenerator may wrap SkPicture data, codec data, or custom data.
152
153 @param imageGenerator stock or custom routines to retrieve SkImage
154 @param subset bounds of returned SkImage; may be nullptr
155 @return created SkImage, or nullptr
156 */
157 static sk_sp<SkImage> MakeFromGenerator(std::unique_ptr<SkImageGenerator> imageGenerator,
158 const SkIRect* subset = nullptr);
159
160 /**
161 * Return an image backed by the encoded data, but attempt to defer decoding until the image
162 * is actually used/drawn. This deferral allows the system to cache the result, either on the
163 * CPU or on the GPU, depending on where the image is drawn. If memory is low, the cache may
164 * be purged, causing the next draw of the image to have to re-decode.
165 *
166 * The subset parameter specifies a area within the decoded image to create the image from.
167 * If subset is null, then the entire image is returned.
168 *
169 * This is similar to DecodeTo[Raster,Texture], but this method will attempt to defer the
170 * actual decode, while the DecodeTo... method explicitly decode and allocate the backend
171 * when the call is made.
172 *
173 * If the encoded format is not supported, or subset is outside of the bounds of the decoded
174 * image, nullptr is returned.
175 *
176 * @param encoded the encoded data
177 * @param length the number of bytes of encoded data
178 * @param subset the bounds of the pixels within the decoded image to return. may be null.
179 * @return created SkImage, or nullptr
180
181 example: https://fiddle.skia.org/c/@Image_MakeFromEncoded
182 */
183 static sk_sp<SkImage> MakeFromEncoded(sk_sp<SkData> encoded, const SkIRect* subset = nullptr);
184
185 /**
186 * Decode the data in encoded/length into a raster image.
187 *
188 * The subset parameter specifies a area within the decoded image to create the image from.
189 * If subset is null, then the entire image is returned.
190 *
191 * This is similar to MakeFromEncoded, but this method will always decode immediately, and
192 * allocate the memory for the pixels for the lifetime of the returned image.
193 *
194 * If the encoded format is not supported, or subset is outside of the bounds of the decoded
195 * image, nullptr is returned.
196 *
197 * @param encoded the encoded data
198 * @param length the number of bytes of encoded data
199 * @param subset the bounds of the pixels within the decoded image to return. may be null.
200 * @return created SkImage, or nullptr
201 */
202 static sk_sp<SkImage> DecodeToRaster(const void* encoded, size_t length,
203 const SkIRect* subset = nullptr);
204 static sk_sp<SkImage> DecodeToRaster(const sk_sp<SkData>& data,
205 const SkIRect* subset = nullptr) {
206 return DecodeToRaster(data->data(), data->size(), subset);
207 }
208
209 /**
210 * Decode the data in encoded/length into a texture-backed image.
211 *
212 * The subset parameter specifies a area within the decoded image to create the image from.
213 * If subset is null, then the entire image is returned.
214 *
215 * This is similar to MakeFromEncoded, but this method will always decode immediately, and
216 * allocate the texture for the pixels for the lifetime of the returned image.
217 *
218 * If the encoded format is not supported, or subset is outside of the bounds of the decoded
219 * image, nullptr is returned.
220 *
221 * @param encoded the encoded data
222 * @param length the number of bytes of encoded data
223 * @param subset the bounds of the pixels within the decoded image to return. may be null.
224 * @return created SkImage, or nullptr
225 */
226 static sk_sp<SkImage> DecodeToTexture(GrContext* ctx, const void* encoded, size_t length,
227 const SkIRect* subset = nullptr);
228 static sk_sp<SkImage> DecodeToTexture(GrContext* ctx, const sk_sp<SkData>& data,
229 const SkIRect* subset = nullptr) {
230 return DecodeToTexture(ctx, data->data(), data->size(), subset);
231 }
232
233 /*
234 * Experimental:
235 * Skia | GL_COMPRESSED_* | MTLPixelFormat* | VK_FORMAT_*_BLOCK
236 * --------------------------------------------------------------------------------------
237 * kETC2_RGB8_UNORM | ETC1_RGB8 | ETC2_RGB8 (iOS-only) | ETC2_R8G8B8_UNORM
238 * | RGB8_ETC2 | |
239 * --------------------------------------------------------------------------------------
240 * kBC1_RGB8_UNORM | RGB_S3TC_DXT1_EXT | N/A | BC1_RGB_UNORM
241 * --------------------------------------------------------------------------------------
242 * kBC1_RGBA8_UNORM | RGBA_S3TC_DXT1_EXT | BC1_RGBA (macOS-only)| BC1_RGBA_UNORM
243 */
244 enum class CompressionType {
245 kNone,
246 kETC2_RGB8_UNORM, // the same as ETC1
247
248 kBC1_RGB8_UNORM,
249 kBC1_RGBA8_UNORM,
250 kLast = kBC1_RGBA8_UNORM,
251 };
252
253 static constexpr int kCompressionTypeCount = static_cast<int>(CompressionType::kLast) + 1;
254
255 static const CompressionType kETC1_CompressionType = CompressionType::kETC2_RGB8_UNORM;
256
257 /** Creates a GPU-backed SkImage from compressed data.
258
259 This method will return an SkImage representing the compressed data.
260 If the GPU doesn't support the specified compression method, the data
261 will be decompressed and then wrapped in a GPU-backed image.
262
263 Note: one can query the supported compression formats via
264 GrContext::compressedBackendFormat.
265
266 @param context GPU context
267 @param data compressed data to store in SkImage
268 @param width width of full SkImage
269 @param height height of full SkImage
270 @param type type of compression used
271 @param mipMapped does 'data' contain data for all the mipmap levels?
272 @param isProtected do the contents of 'data' require DRM protection (on Vulkan)?
273 @return created SkImage, or nullptr
274 */
275 static sk_sp<SkImage> MakeTextureFromCompressed(GrContext* context,
276 sk_sp<SkData> data,
277 int width, int height,
278 CompressionType type,
279 GrMipMapped mipMapped = GrMipMapped::kNo,
280 GrProtected isProtected = GrProtected::kNo);
281 /** To be deprecated. Use MakeTextureFromCompressed.
282 */
283 static sk_sp<SkImage> MakeFromCompressed(GrContext* context,
284 sk_sp<SkData> data,
285 int width, int height,
286 CompressionType type,
287 GrMipMapped mipMapped = GrMipMapped::kNo,
288 GrProtected isProtected = GrProtected::kNo) {
289 return MakeTextureFromCompressed(context, data, width, height, type,
290 mipMapped, isProtected);
291
292 }
293
294 /** Creates a CPU-backed SkImage from compressed data.
295
296 This method will decompress the compressed data and create an image wrapping
297 it. Any mipmap levels present in the compressed data are discarded.
298
299 @param data compressed data to store in SkImage
300 @param width width of full SkImage
301 @param height height of full SkImage
302 @param type type of compression used
303 @return created SkImage, or nullptr
304 */
305 static sk_sp<SkImage> MakeRasterFromCompressed(sk_sp<SkData> data,
306 int width, int height,
307 CompressionType type);
308
309 /** User function called when supplied texture may be deleted.
310 */
311 typedef void (*TextureReleaseProc)(ReleaseContext releaseContext);
312
313 /** Creates SkImage from GPU texture associated with context. Caller is responsible for
314 managing the lifetime of GPU texture.
315
316 SkImage is returned if format of backendTexture is recognized and supported.
317 Recognized formats vary by GPU back-end.
318
319 @param context GPU context
320 @param backendTexture texture residing on GPU
321 @param colorSpace range of colors; may be nullptr
322 @return created SkImage, or nullptr
323 */
324 static sk_sp<SkImage> MakeFromTexture(GrContext* context,
325 const GrBackendTexture& backendTexture,
326 GrSurfaceOrigin origin,
327 SkColorType colorType,
328 SkAlphaType alphaType,
329 sk_sp<SkColorSpace> colorSpace) {
330 return MakeFromTexture(context, backendTexture, origin, colorType, alphaType, colorSpace,
331 nullptr, nullptr);
332 }
333
334 /** Creates SkImage from GPU texture associated with context. GPU texture must stay
335 valid and unchanged until textureReleaseProc is called. textureReleaseProc is
336 passed releaseContext when SkImage is deleted or no longer refers to texture.
337
338 SkImage is returned if format of backendTexture is recognized and supported.
339 Recognized formats vary by GPU back-end.
340
341 @param context GPU context
342 @param backendTexture texture residing on GPU
343 @param colorSpace This describes the color space of this image's contents, as
344 seen after sampling. In general, if the format of the backend
345 texture is SRGB, some linear colorSpace should be supplied
346 (e.g., SkColorSpace::MakeSRGBLinear()). If the format of the
347 backend texture is linear, then the colorSpace should include
348 a description of the transfer function as
349 well (e.g., SkColorSpace::MakeSRGB()).
350 @param textureReleaseProc function called when texture can be released
351 @param releaseContext state passed to textureReleaseProc
352 @return created SkImage, or nullptr
353 */
354 static sk_sp<SkImage> MakeFromTexture(GrContext* context,
355 const GrBackendTexture& backendTexture,
356 GrSurfaceOrigin origin,
357 SkColorType colorType,
358 SkAlphaType alphaType,
359 sk_sp<SkColorSpace> colorSpace,
360 TextureReleaseProc textureReleaseProc,
361 ReleaseContext releaseContext);
362
363 /** Creates an SkImage from a GPU backend texture. The backend texture must stay
364 valid and unchanged until textureReleaseProc is called. The textureReleaseProc is
365 called when the SkImage is deleted or no longer refers to the texture and will be
366 passed the releaseContext.
367
368 An SkImage is returned if the format of backendTexture is recognized and supported.
369 Recognized formats vary by GPU back-end.
370
371 @param context the GPU context
372 @param backendTexture a texture already allocated by the GPU
373 @param alphaType This characterizes the nature of the alpha values in the
374 backend texture. For opaque compressed formats (e.g., ETC1)
375 this should usually be set to kOpaque_SkAlphaType.
376 @param colorSpace This describes the color space of this image's contents, as
377 seen after sampling. In general, if the format of the backend
378 texture is SRGB, some linear colorSpace should be supplied
379 (e.g., SkColorSpace::MakeSRGBLinear()). If the format of the
380 backend texture is linear, then the colorSpace should include
381 a description of the transfer function as
382 well (e.g., SkColorSpace::MakeSRGB()).
383 @param textureReleaseProc function called when the backend texture can be released
384 @param releaseContext state passed to textureReleaseProc
385 @return created SkImage, or nullptr
386 */
387 static sk_sp<SkImage> MakeFromCompressedTexture(GrContext* context,
388 const GrBackendTexture& backendTexture,
389 GrSurfaceOrigin origin,
390 SkAlphaType alphaType,
391 sk_sp<SkColorSpace> colorSpace,
392 TextureReleaseProc textureReleaseProc = nullptr,
393 ReleaseContext releaseContext = nullptr);
394
395 /** Creates SkImage from pixmap. SkImage is uploaded to GPU back-end using context.
396
397 Created SkImage is available to other GPU contexts, and is available across thread
398 boundaries. All contexts must be in the same GPU share group, or otherwise
399 share resources.
400
401 When SkImage is no longer referenced, context releases texture memory
402 asynchronously.
403
404 GrBackendTexture created from pixmap is uploaded to match SkSurface created with
405 dstColorSpace. SkColorSpace of SkImage is determined by pixmap.colorSpace().
406
407 SkImage is returned referring to GPU back-end if context is not nullptr,
408 format of data is recognized and supported, and if context supports moving
409 resources between contexts. Otherwise, pixmap pixel data is copied and SkImage
410 as returned in raster format if possible; nullptr may be returned.
411 Recognized GPU formats vary by platform and GPU back-end.
412
413 @param context GPU context
414 @param pixmap SkImageInfo, pixel address, and row bytes
415 @param buildMips create SkImage as mip map if true
416 @param dstColorSpace range of colors of matching SkSurface on GPU
417 @param limitToMaxTextureSize downscale image to GPU maximum texture size, if necessary
418 @return created SkImage, or nullptr
419 */
420 static sk_sp<SkImage> MakeCrossContextFromPixmap(GrContext* context, const SkPixmap& pixmap,
421 bool buildMips,
422 bool limitToMaxTextureSize = false);
423
424 /** Creates SkImage from backendTexture associated with context. backendTexture and
425 returned SkImage are managed internally, and are released when no longer needed.
426
427 SkImage is returned if format of backendTexture is recognized and supported.
428 Recognized formats vary by GPU back-end.
429
430 @param context GPU context
431 @param backendTexture texture residing on GPU
432 @param colorSpace range of colors; may be nullptr
433 @return created SkImage, or nullptr
434 */
435 static sk_sp<SkImage> MakeFromAdoptedTexture(GrContext* context,
436 const GrBackendTexture& backendTexture,
437 GrSurfaceOrigin surfaceOrigin,
438 SkColorType colorType,
439 SkAlphaType alphaType = kPremul_SkAlphaType,
440 sk_sp<SkColorSpace> colorSpace = nullptr);
441
442 /** Creates an SkImage by flattening the specified YUVA planes into a single, interleaved RGBA
443 image.
444
445 @param context GPU context
446 @param yuvColorSpace How the YUV values are converted to RGB
447 @param yuvaTextures array of (up to four) YUVA textures on GPU which contain the,
448 possibly interleaved, YUVA planes
449 @param yuvaIndices array indicating which texture in yuvaTextures, and channel
450 in that texture, maps to each component of YUVA.
451 @param imageSize size of the resulting image
452 @param imageOrigin origin of the resulting image.
453 @param imageColorSpace range of colors of the resulting image; may be nullptr
454 @return created SkImage, or nullptr
455 */
456 static sk_sp<SkImage> MakeFromYUVATexturesCopy(GrContext* context,
457 SkYUVColorSpace yuvColorSpace,
458 const GrBackendTexture yuvaTextures[],
459 const SkYUVAIndex yuvaIndices[4],
460 SkISize imageSize,
461 GrSurfaceOrigin imageOrigin,
462 sk_sp<SkColorSpace> imageColorSpace = nullptr);
463
464 /** Creates an SkImage by flattening the specified YUVA planes into a single, interleaved RGBA
465 image. 'backendTexture' is used to store the result of the flattening.
466
467 @param context GPU context
468 @param yuvColorSpace How the YUV values are converted to RGB
469 @param yuvaTextures array of (up to four) YUVA textures on GPU which contain the,
470 possibly interleaved, YUVA planes
471 @param yuvaIndices array indicating which texture in yuvaTextures, and channel
472 in that texture, maps to each component of YUVA.
473 @param imageSize size of the resulting image
474 @param imageOrigin origin of the resulting image.
475 @param backendTexture the resource that stores the final pixels
476 @param imageColorSpace range of colors of the resulting image; may be nullptr
477 @param textureReleaseProc function called when backendTexture can be released
478 @param releaseContext state passed to textureReleaseProc
479 @return created SkImage, or nullptr
480 */
481 static sk_sp<SkImage> MakeFromYUVATexturesCopyWithExternalBackend(
482 GrContext* context,
483 SkYUVColorSpace yuvColorSpace,
484 const GrBackendTexture yuvaTextures[],
485 const SkYUVAIndex yuvaIndices[4],
486 SkISize imageSize,
487 GrSurfaceOrigin imageOrigin,
488 const GrBackendTexture& backendTexture,
489 sk_sp<SkColorSpace> imageColorSpace = nullptr,
490 TextureReleaseProc textureReleaseProc = nullptr,
491 ReleaseContext releaseContext = nullptr);
492
493 /** Creates an SkImage by storing the specified YUVA planes into an image, to be rendered
494 via multitexturing.
495
496 @param context GPU context
497 @param yuvColorSpace How the YUV values are converted to RGB
498 @param yuvaTextures array of (up to four) YUVA textures on GPU which contain the,
499 possibly interleaved, YUVA planes
500 @param yuvaIndices array indicating which texture in yuvaTextures, and channel
501 in that texture, maps to each component of YUVA.
502 @param imageSize size of the resulting image
503 @param imageOrigin origin of the resulting image.
504 @param imageColorSpace range of colors of the resulting image; may be nullptr
505 @return created SkImage, or nullptr
506 */
507 static sk_sp<SkImage> MakeFromYUVATextures(GrContext* context,
508 SkYUVColorSpace yuvColorSpace,
509 const GrBackendTexture yuvaTextures[],
510 const SkYUVAIndex yuvaIndices[4],
511 SkISize imageSize,
512 GrSurfaceOrigin imageOrigin,
513 sk_sp<SkColorSpace> imageColorSpace = nullptr);
514
515 /** Creates SkImage from pixmap array representing YUVA data.
516 SkImage is uploaded to GPU back-end using context.
517
518 Each GrBackendTexture created from yuvaPixmaps array is uploaded to match SkSurface
519 using SkColorSpace of SkPixmap. SkColorSpace of SkImage is determined by imageColorSpace.
520
521 SkImage is returned referring to GPU back-end if context is not nullptr and
522 format of data is recognized and supported. Otherwise, nullptr is returned.
523 Recognized GPU formats vary by platform and GPU back-end.
524
525 @param context GPU context
526 @param yuvColorSpace How the YUV values are converted to RGB
527 @param yuvaPixmaps array of (up to four) SkPixmap which contain the,
528 possibly interleaved, YUVA planes
529 @param yuvaIndices array indicating which pixmap in yuvaPixmaps, and channel
530 in that pixmap, maps to each component of YUVA.
531 @param imageSize size of the resulting image
532 @param imageOrigin origin of the resulting image.
533 @param buildMips create internal YUVA textures as mip map if true
534 @param limitToMaxTextureSize downscale image to GPU maximum texture size, if necessary
535 @param imageColorSpace range of colors of the resulting image; may be nullptr
536 @return created SkImage, or nullptr
537 */
538 static sk_sp<SkImage> MakeFromYUVAPixmaps(
539 GrContext* context, SkYUVColorSpace yuvColorSpace, const SkPixmap yuvaPixmaps[],
540 const SkYUVAIndex yuvaIndices[4], SkISize imageSize, GrSurfaceOrigin imageOrigin,
541 bool buildMips, bool limitToMaxTextureSize = false,
542 sk_sp<SkColorSpace> imageColorSpace = nullptr);
543
544 /** To be deprecated.
545 */
546 static sk_sp<SkImage> MakeFromYUVTexturesCopy(GrContext* context, SkYUVColorSpace yuvColorSpace,
547 const GrBackendTexture yuvTextures[3],
548 GrSurfaceOrigin imageOrigin,
549 sk_sp<SkColorSpace> imageColorSpace = nullptr);
550
551 /** To be deprecated.
552 */
553 static sk_sp<SkImage> MakeFromYUVTexturesCopyWithExternalBackend(
554 GrContext* context,
555 SkYUVColorSpace yuvColorSpace,
556 const GrBackendTexture yuvTextures[3],
557 GrSurfaceOrigin imageOrigin,
558 const GrBackendTexture& backendTexture,
559 sk_sp<SkColorSpace> imageColorSpace = nullptr);
560
561 /** Creates SkImage from copy of nv12Textures, an array of textures on GPU.
562 nv12Textures[0] contains pixels for YUV component y plane.
563 nv12Textures[1] contains pixels for YUV component u plane,
564 followed by pixels for YUV component v plane.
565 Returned SkImage has the dimensions nv12Textures[2].
566 yuvColorSpace describes how YUV colors convert to RGB colors.
567
568 @param context GPU context
569 @param yuvColorSpace How the YUV values are converted to RGB
570 @param nv12Textures array of YUV textures on GPU
571 @param imageColorSpace range of colors; may be nullptr
572 @return created SkImage, or nullptr
573 */
574 static sk_sp<SkImage> MakeFromNV12TexturesCopy(GrContext* context,
575 SkYUVColorSpace yuvColorSpace,
576 const GrBackendTexture nv12Textures[2],
577 GrSurfaceOrigin imageOrigin,
578 sk_sp<SkColorSpace> imageColorSpace = nullptr);
579
580 /** Creates SkImage from copy of nv12Textures, an array of textures on GPU.
581 nv12Textures[0] contains pixels for YUV component y plane.
582 nv12Textures[1] contains pixels for YUV component u plane,
583 followed by pixels for YUV component v plane.
584 Returned SkImage has the dimensions nv12Textures[2] and stores pixels in backendTexture.
585 yuvColorSpace describes how YUV colors convert to RGB colors.
586
587 @param context GPU context
588 @param yuvColorSpace How the YUV values are converted to RGB
589 @param nv12Textures array of YUV textures on GPU
590 @param backendTexture the resource that stores the final pixels
591 @param imageColorSpace range of colors; may be nullptr
592 @param textureReleaseProc function called when backendTexture can be released
593 @param releaseContext state passed to textureReleaseProc
594 @return created SkImage, or nullptr
595 */
596 static sk_sp<SkImage> MakeFromNV12TexturesCopyWithExternalBackend(
597 GrContext* context,
598 SkYUVColorSpace yuvColorSpace,
599 const GrBackendTexture nv12Textures[2],
600 GrSurfaceOrigin imageOrigin,
601 const GrBackendTexture& backendTexture,
602 sk_sp<SkColorSpace> imageColorSpace = nullptr,
603 TextureReleaseProc textureReleaseProc = nullptr,
604 ReleaseContext releaseContext = nullptr);
605
606 enum class BitDepth {
607 kU8, //!< uses 8-bit unsigned int per color component
608 kF16, //!< uses 16-bit float per color component
609 };
610
611 /** Creates SkImage from picture. Returned SkImage width and height are set by dimensions.
612 SkImage draws picture with matrix and paint, set to bitDepth and colorSpace.
613
614 If matrix is nullptr, draws with identity SkMatrix. If paint is nullptr, draws
615 with default SkPaint. colorSpace may be nullptr.
616
617 @param picture stream of drawing commands
618 @param dimensions width and height
619 @param matrix SkMatrix to rotate, scale, translate, and so on; may be nullptr
620 @param paint SkPaint to apply transparency, filtering, and so on; may be nullptr
621 @param bitDepth 8-bit integer or 16-bit float: per component
622 @param colorSpace range of colors; may be nullptr
623 @return created SkImage, or nullptr
624 */
625 static sk_sp<SkImage> MakeFromPicture(sk_sp<SkPicture> picture, const SkISize& dimensions,
626 const SkMatrix* matrix, const SkPaint* paint,
627 BitDepth bitDepth,
628 sk_sp<SkColorSpace> colorSpace);
629
630#if defined(SK_BUILD_FOR_ANDROID) && __ANDROID_API__ >= 26
631 /** (See Skia bug 7447)
632 Creates SkImage from Android hardware buffer.
633 Returned SkImage takes a reference on the buffer.
634
635 Only available on Android, when __ANDROID_API__ is defined to be 26 or greater.
636
637 @param hardwareBuffer AHardwareBuffer Android hardware buffer
638 @param colorSpace range of colors; may be nullptr
639 @return created SkImage, or nullptr
640 */
641 static sk_sp<SkImage> MakeFromAHardwareBuffer(
642 AHardwareBuffer* hardwareBuffer,
643 SkAlphaType alphaType = kPremul_SkAlphaType,
644 sk_sp<SkColorSpace> colorSpace = nullptr,
645 GrSurfaceOrigin surfaceOrigin = kTopLeft_GrSurfaceOrigin);
646
647 /** Creates SkImage from Android hardware buffer and uploads the data from the SkPixmap to it.
648 Returned SkImage takes a reference on the buffer.
649
650 Only available on Android, when __ANDROID_API__ is defined to be 26 or greater.
651
652 @param pixmap SkPixmap that contains data to be uploaded to the AHardwareBuffer
653 @param hardwareBuffer AHardwareBuffer Android hardware buffer
654 @return created SkImage, or nullptr
655 */
656 static sk_sp<SkImage> MakeFromAHardwareBufferWithData(
657 GrContext* context,
658 const SkPixmap& pixmap,
659 AHardwareBuffer* hardwareBuffer,
660 GrSurfaceOrigin surfaceOrigin = kTopLeft_GrSurfaceOrigin);
661#endif
662
663 /** Returns a SkImageInfo describing the width, height, color type, alpha type, and color space
664 of the SkImage.
665
666 @return image info of SkImage.
667 */
668 const SkImageInfo& imageInfo() const { return fInfo; }
669
670 /** Returns pixel count in each row.
671
672 @return pixel width in SkImage
673 */
674 int width() const { return fInfo.width(); }
675
676 /** Returns pixel row count.
677
678 @return pixel height in SkImage
679 */
680 int height() const { return fInfo.height(); }
681
682 /** Returns SkISize { width(), height() }.
683
684 @return integral size of width() and height()
685 */
686 SkISize dimensions() const { return SkISize::Make(fInfo.width(), fInfo.height()); }
687
688 /** Returns SkIRect { 0, 0, width(), height() }.
689
690 @return integral rectangle from origin to width() and height()
691 */
692 SkIRect bounds() const { return SkIRect::MakeWH(fInfo.width(), fInfo.height()); }
693
694 /** Returns value unique to image. SkImage contents cannot change after SkImage is
695 created. Any operation to create a new SkImage will receive generate a new
696 unique number.
697
698 @return unique identifier
699 */
700 uint32_t uniqueID() const { return fUniqueID; }
701
702 /** Returns SkAlphaType.
703
704 SkAlphaType returned was a parameter to an SkImage constructor,
705 or was parsed from encoded data.
706
707 @return SkAlphaType in SkImage
708
709 example: https://fiddle.skia.org/c/@Image_alphaType
710 */
711 SkAlphaType alphaType() const;
712
713 /** Returns SkColorType if known; otherwise, returns kUnknown_SkColorType.
714
715 @return SkColorType of SkImage
716
717 example: https://fiddle.skia.org/c/@Image_colorType
718 */
719 SkColorType colorType() const;
720
721 /** Returns SkColorSpace, the range of colors, associated with SkImage. The
722 reference count of SkColorSpace is unchanged. The returned SkColorSpace is
723 immutable.
724
725 SkColorSpace returned was passed to an SkImage constructor,
726 or was parsed from encoded data. SkColorSpace returned may be ignored when SkImage
727 is drawn, depending on the capabilities of the SkSurface receiving the drawing.
728
729 @return SkColorSpace in SkImage, or nullptr
730
731 example: https://fiddle.skia.org/c/@Image_colorSpace
732 */
733 SkColorSpace* colorSpace() const;
734
735 /** Returns a smart pointer to SkColorSpace, the range of colors, associated with
736 SkImage. The smart pointer tracks the number of objects sharing this
737 SkColorSpace reference so the memory is released when the owners destruct.
738
739 The returned SkColorSpace is immutable.
740
741 SkColorSpace returned was passed to an SkImage constructor,
742 or was parsed from encoded data. SkColorSpace returned may be ignored when SkImage
743 is drawn, depending on the capabilities of the SkSurface receiving the drawing.
744
745 @return SkColorSpace in SkImage, or nullptr, wrapped in a smart pointer
746
747 example: https://fiddle.skia.org/c/@Image_refColorSpace
748 */
749 sk_sp<SkColorSpace> refColorSpace() const;
750
751 /** Returns true if SkImage pixels represent transparency only. If true, each pixel
752 is packed in 8 bits as defined by kAlpha_8_SkColorType.
753
754 @return true if pixels represent a transparency mask
755
756 example: https://fiddle.skia.org/c/@Image_isAlphaOnly
757 */
758 bool isAlphaOnly() const;
759
760 /** Returns true if pixels ignore their alpha value and are treated as fully opaque.
761
762 @return true if SkAlphaType is kOpaque_SkAlphaType
763 */
764 bool isOpaque() const { return SkAlphaTypeIsOpaque(this->alphaType()); }
765
766 /** Creates SkShader from SkImage. SkShader dimensions are taken from SkImage. SkShader uses
767 SkTileMode rules to fill drawn area outside SkImage. localMatrix permits
768 transforming SkImage before SkCanvas matrix is applied.
769
770 @param tmx tiling in the x direction
771 @param tmy tiling in the y direction
772 @param localMatrix SkImage transformation, or nullptr
773 @return SkShader containing SkImage
774 */
775 sk_sp<SkShader> makeShader(SkTileMode tmx, SkTileMode tmy,
776 const SkMatrix* localMatrix = nullptr) const;
777 sk_sp<SkShader> makeShader(SkTileMode tmx, SkTileMode tmy, const SkMatrix& localMatrix) const {
778 return this->makeShader(tmx, tmy, &localMatrix);
779 }
780
781 /** Creates SkShader from SkImage. SkShader dimensions are taken from SkImage. SkShader uses
782 SkShader::kClamp_TileMode to fill drawn area outside SkImage. localMatrix permits
783 transforming SkImage before SkCanvas matrix is applied.
784
785 @param localMatrix SkImage transformation, or nullptr
786 @return SkShader containing SkImage
787 */
788 sk_sp<SkShader> makeShader(const SkMatrix* localMatrix = nullptr) const {
789 return this->makeShader(SkTileMode::kClamp, SkTileMode::kClamp, localMatrix);
790 }
791 sk_sp<SkShader> makeShader(const SkMatrix& localMatrix) const {
792 return this->makeShader(SkTileMode::kClamp, SkTileMode::kClamp, &localMatrix);
793 }
794
795
796 /** Copies SkImage pixel address, row bytes, and SkImageInfo to pixmap, if address
797 is available, and returns true. If pixel address is not available, return
798 false and leave pixmap unchanged.
799
800 @param pixmap storage for pixel state if pixels are readable; otherwise, ignored
801 @return true if SkImage has direct access to pixels
802
803 example: https://fiddle.skia.org/c/@Image_peekPixels
804 */
805 bool peekPixels(SkPixmap* pixmap) const;
806
807 /** Returns true the contents of SkImage was created on or uploaded to GPU memory,
808 and is available as a GPU texture.
809
810 @return true if SkImage is a GPU texture
811
812 example: https://fiddle.skia.org/c/@Image_isTextureBacked
813 */
814 bool isTextureBacked() const;
815
816 /** Returns true if SkImage can be drawn on either raster surface or GPU surface.
817 If context is nullptr, tests if SkImage draws on raster surface;
818 otherwise, tests if SkImage draws on GPU surface associated with context.
819
820 SkImage backed by GPU texture may become invalid if associated GrContext is
821 invalid. lazy image may be invalid and may not draw to raster surface or
822 GPU surface or both.
823
824 @param context GPU context
825 @return true if SkImage can be drawn
826
827 example: https://fiddle.skia.org/c/@Image_isValid
828 */
829 bool isValid(GrContext* context) const;
830
831 /** Flushes any pending uses of texture-backed images in the GPU backend. If the image is not
832 texture-backed (including promise texture images) or if the the GrContext does not
833 have the same context ID as the context backing the image then this is a no-op.
834
835 If the image was not used in any non-culled draws recorded on the passed GrContext then
836 this is a no-op unless the GrFlushInfo contains semaphores, a finish proc, or uses
837 kSyncCpu_GrFlushFlag. Those are respected even when the image has not been used.
838
839 @param context the context on which to flush pending usages of the image.
840 @param info flush options
841 */
842 GrSemaphoresSubmitted flush(GrContext* context, const GrFlushInfo& flushInfo);
843
844 /** Version of flush() that uses a default GrFlushInfo. */
845 void flush(GrContext*);
846
847 /** Retrieves the back-end texture. If SkImage has no back-end texture, an invalid
848 object is returned. Call GrBackendTexture::isValid to determine if the result
849 is valid.
850
851 If flushPendingGrContextIO is true, completes deferred I/O operations.
852
853 If origin in not nullptr, copies location of content drawn into SkImage.
854
855 @param flushPendingGrContextIO flag to flush outstanding requests
856 @return back-end API texture handle; invalid on failure
857 */
858 GrBackendTexture getBackendTexture(bool flushPendingGrContextIO,
859 GrSurfaceOrigin* origin = nullptr) const;
860
861 /** \enum SkImage::CachingHint
862 CachingHint selects whether Skia may internally cache SkBitmap generated by
863 decoding SkImage, or by copying SkImage from GPU to CPU. The default behavior
864 allows caching SkBitmap.
865
866 Choose kDisallow_CachingHint if SkImage pixels are to be used only once, or
867 if SkImage pixels reside in a cache outside of Skia, or to reduce memory pressure.
868
869 Choosing kAllow_CachingHint does not ensure that pixels will be cached.
870 SkImage pixels may not be cached if memory requirements are too large or
871 pixels are not accessible.
872 */
873 enum CachingHint {
874 kAllow_CachingHint, //!< allows internally caching decoded and copied pixels
875 kDisallow_CachingHint, //!< disallows internally caching decoded and copied pixels
876 };
877
878 /** Copies SkRect of pixels from SkImage to dstPixels. Copy starts at offset (srcX, srcY),
879 and does not exceed SkImage (width(), height()).
880
881 dstInfo specifies width, height, SkColorType, SkAlphaType, and SkColorSpace of
882 destination. dstRowBytes specifies the gap from one destination row to the next.
883 Returns true if pixels are copied. Returns false if:
884 - dstInfo.addr() equals nullptr
885 - dstRowBytes is less than dstInfo.minRowBytes()
886 - SkPixelRef is nullptr
887
888 Pixels are copied only if pixel conversion is possible. If SkImage SkColorType is
889 kGray_8_SkColorType, or kAlpha_8_SkColorType; dstInfo.colorType() must match.
890 If SkImage SkColorType is kGray_8_SkColorType, dstInfo.colorSpace() must match.
891 If SkImage SkAlphaType is kOpaque_SkAlphaType, dstInfo.alphaType() must
892 match. If SkImage SkColorSpace is nullptr, dstInfo.colorSpace() must match. Returns
893 false if pixel conversion is not possible.
894
895 srcX and srcY may be negative to copy only top or left of source. Returns
896 false if width() or height() is zero or negative.
897 Returns false if abs(srcX) >= Image width(), or if abs(srcY) >= Image height().
898
899 If cachingHint is kAllow_CachingHint, pixels may be retained locally.
900 If cachingHint is kDisallow_CachingHint, pixels are not added to the local cache.
901
902 @param dstInfo destination width, height, SkColorType, SkAlphaType, SkColorSpace
903 @param dstPixels destination pixel storage
904 @param dstRowBytes destination row length
905 @param srcX column index whose absolute value is less than width()
906 @param srcY row index whose absolute value is less than height()
907 @return true if pixels are copied to dstPixels
908 */
909 bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes,
910 int srcX, int srcY, CachingHint cachingHint = kAllow_CachingHint) const;
911
912 /** Copies a SkRect of pixels from SkImage to dst. Copy starts at (srcX, srcY), and
913 does not exceed SkImage (width(), height()).
914
915 dst specifies width, height, SkColorType, SkAlphaType, SkColorSpace, pixel storage,
916 and row bytes of destination. dst.rowBytes() specifics the gap from one destination
917 row to the next. Returns true if pixels are copied. Returns false if:
918 - dst pixel storage equals nullptr
919 - dst.rowBytes is less than SkImageInfo::minRowBytes
920 - SkPixelRef is nullptr
921
922 Pixels are copied only if pixel conversion is possible. If SkImage SkColorType is
923 kGray_8_SkColorType, or kAlpha_8_SkColorType; dst.colorType() must match.
924 If SkImage SkColorType is kGray_8_SkColorType, dst.colorSpace() must match.
925 If SkImage SkAlphaType is kOpaque_SkAlphaType, dst.alphaType() must
926 match. If SkImage SkColorSpace is nullptr, dst.colorSpace() must match. Returns
927 false if pixel conversion is not possible.
928
929 srcX and srcY may be negative to copy only top or left of source. Returns
930 false if width() or height() is zero or negative.
931 Returns false if abs(srcX) >= Image width(), or if abs(srcY) >= Image height().
932
933 If cachingHint is kAllow_CachingHint, pixels may be retained locally.
934 If cachingHint is kDisallow_CachingHint, pixels are not added to the local cache.
935
936 @param dst destination SkPixmap: SkImageInfo, pixels, row bytes
937 @param srcX column index whose absolute value is less than width()
938 @param srcY row index whose absolute value is less than height()
939 @return true if pixels are copied to dst
940 */
941 bool readPixels(const SkPixmap& dst, int srcX, int srcY,
942 CachingHint cachingHint = kAllow_CachingHint) const;
943
944 /** Copies SkImage to dst, scaling pixels to fit dst.width() and dst.height(), and
945 converting pixels to match dst.colorType() and dst.alphaType(). Returns true if
946 pixels are copied. Returns false if dst.addr() is nullptr, or dst.rowBytes() is
947 less than dst SkImageInfo::minRowBytes.
948
949 Pixels are copied only if pixel conversion is possible. If SkImage SkColorType is
950 kGray_8_SkColorType, or kAlpha_8_SkColorType; dst.colorType() must match.
951 If SkImage SkColorType is kGray_8_SkColorType, dst.colorSpace() must match.
952 If SkImage SkAlphaType is kOpaque_SkAlphaType, dst.alphaType() must
953 match. If SkImage SkColorSpace is nullptr, dst.colorSpace() must match. Returns
954 false if pixel conversion is not possible.
955
956 Scales the image, with filterQuality, to match dst.width() and dst.height().
957 filterQuality kNone_SkFilterQuality is fastest, typically implemented with
958 nearest neighbor filter. kLow_SkFilterQuality is typically implemented with
959 bilerp filter. kMedium_SkFilterQuality is typically implemented with
960 bilerp filter, and mip-map filter when size is reduced.
961 kHigh_SkFilterQuality is slowest, typically implemented with bicubic filter.
962
963 If cachingHint is kAllow_CachingHint, pixels may be retained locally.
964 If cachingHint is kDisallow_CachingHint, pixels are not added to the local cache.
965
966 @param dst destination SkPixmap: SkImageInfo, pixels, row bytes
967 @return true if pixels are scaled to fit dst
968 */
969 bool scalePixels(const SkPixmap& dst, SkFilterQuality filterQuality,
970 CachingHint cachingHint = kAllow_CachingHint) const;
971
972 /** Encodes SkImage pixels, returning result as SkData.
973
974 Returns nullptr if encoding fails, or if encodedImageFormat is not supported.
975
976 SkImage encoding in a format requires both building with one or more of:
977 SK_ENCODE_JPEG, SK_ENCODE_PNG, SK_ENCODE_WEBP; and platform support
978 for the encoded format.
979
980 If SK_BUILD_FOR_MAC or SK_BUILD_FOR_IOS is defined, encodedImageFormat can
981 additionally be one of: SkEncodedImageFormat::kICO, SkEncodedImageFormat::kBMP,
982 SkEncodedImageFormat::kGIF.
983
984 quality is a platform and format specific metric trading off size and encoding
985 error. When used, quality equaling 100 encodes with the least error. quality may
986 be ignored by the encoder.
987
988 @param encodedImageFormat one of: SkEncodedImageFormat::kJPEG, SkEncodedImageFormat::kPNG,
989 SkEncodedImageFormat::kWEBP
990 @param quality encoder specific metric with 100 equaling best
991 @return encoded SkImage, or nullptr
992
993 example: https://fiddle.skia.org/c/@Image_encodeToData
994 */
995 sk_sp<SkData> encodeToData(SkEncodedImageFormat encodedImageFormat, int quality) const;
996
997 /** Encodes SkImage pixels, returning result as SkData. Returns existing encoded data
998 if present; otherwise, SkImage is encoded with SkEncodedImageFormat::kPNG. Skia
999 must be built with SK_ENCODE_PNG to encode SkImage.
1000
1001 Returns nullptr if existing encoded data is missing or invalid, and
1002 encoding fails.
1003
1004 @return encoded SkImage, or nullptr
1005
1006 example: https://fiddle.skia.org/c/@Image_encodeToData_2
1007 */
1008 sk_sp<SkData> encodeToData() const;
1009
1010 /** Returns encoded SkImage pixels as SkData, if SkImage was created from supported
1011 encoded stream format. Platform support for formats vary and may require building
1012 with one or more of: SK_ENCODE_JPEG, SK_ENCODE_PNG, SK_ENCODE_WEBP.
1013
1014 Returns nullptr if SkImage contents are not encoded.
1015
1016 @return encoded SkImage, or nullptr
1017
1018 example: https://fiddle.skia.org/c/@Image_refEncodedData
1019 */
1020 sk_sp<SkData> refEncodedData() const;
1021
1022 /** Returns subset of SkImage. subset must be fully contained by SkImage dimensions().
1023 The implementation may share pixels, or may copy them.
1024
1025 Returns nullptr if subset is empty, or subset is not contained by bounds, or
1026 pixels in SkImage could not be read or copied.
1027
1028 @param subset bounds of returned SkImage
1029 @return partial or full SkImage, or nullptr
1030
1031 example: https://fiddle.skia.org/c/@Image_makeSubset
1032 */
1033 sk_sp<SkImage> makeSubset(const SkIRect& subset) const;
1034
1035 /** Returns SkImage backed by GPU texture associated with context. Returned SkImage is
1036 compatible with SkSurface created with dstColorSpace. The returned SkImage respects
1037 mipMapped setting; if mipMapped equals GrMipMapped::kYes, the backing texture
1038 allocates mip map levels.
1039
1040 The mipMapped parameter is effectively treated as kNo if MIP maps are not supported by the
1041 GPU.
1042
1043 Returns original SkImage if the image is already texture-backed, the context matches, and
1044 mipMapped is compatible with the backing GPU texture. SkBudgeted is ignored in this case.
1045
1046 Returns nullptr if context is nullptr, or if SkImage was created with another
1047 GrContext.
1048
1049 @param GrContext GPU context
1050 @param GrMipMapped whether created SkImage texture must allocate mip map levels
1051 @param SkBudgeted whether to count a newly created texture for the returned image
1052 counts against the GrContext's budget.
1053 @return created SkImage, or nullptr
1054 */
1055 sk_sp<SkImage> makeTextureImage(GrContext*,
1056 GrMipMapped = GrMipMapped::kNo,
1057 SkBudgeted = SkBudgeted::kYes) const;
1058
1059 /** Returns raster image or lazy image. Copies SkImage backed by GPU texture into
1060 CPU memory if needed. Returns original SkImage if decoded in raster bitmap,
1061 or if encoded in a stream.
1062
1063 Returns nullptr if backed by GPU texture and copy fails.
1064
1065 @return raster image, lazy image, or nullptr
1066
1067 example: https://fiddle.skia.org/c/@Image_makeNonTextureImage
1068 */
1069 sk_sp<SkImage> makeNonTextureImage() const;
1070
1071 /** Returns raster image. Copies SkImage backed by GPU texture into CPU memory,
1072 or decodes SkImage from lazy image. Returns original SkImage if decoded in
1073 raster bitmap.
1074
1075 Returns nullptr if copy, decode, or pixel read fails.
1076
1077 If cachingHint is kAllow_CachingHint, pixels may be retained locally.
1078 If cachingHint is kDisallow_CachingHint, pixels are not added to the local cache.
1079
1080 @return raster image, or nullptr
1081
1082 example: https://fiddle.skia.org/c/@Image_makeRasterImage
1083 */
1084 sk_sp<SkImage> makeRasterImage(CachingHint cachingHint = kDisallow_CachingHint) const;
1085
1086 /** Creates filtered SkImage. filter processes original SkImage, potentially changing
1087 color, position, and size. subset is the bounds of original SkImage processed
1088 by filter. clipBounds is the expected bounds of the filtered SkImage. outSubset
1089 is required storage for the actual bounds of the filtered SkImage. offset is
1090 required storage for translation of returned SkImage.
1091
1092 Returns nullptr if SkImage could not be created. If nullptr is returned, outSubset
1093 and offset are undefined.
1094
1095 Useful for animation of SkImageFilter that varies size from frame to frame.
1096 Returned SkImage is created larger than required by filter so that GPU texture
1097 can be reused with different sized effects. outSubset describes the valid bounds
1098 of GPU texture returned. offset translates the returned SkImage to keep subsequent
1099 animation frames aligned with respect to each other.
1100
1101 @param context the GrContext in play - if it exists
1102 @param filter how SkImage is sampled when transformed
1103 @param subset bounds of SkImage processed by filter
1104 @param clipBounds expected bounds of filtered SkImage
1105 @param outSubset storage for returned SkImage bounds
1106 @param offset storage for returned SkImage translation
1107 @return filtered SkImage, or nullptr
1108 */
1109 sk_sp<SkImage> makeWithFilter(GrContext* context,
1110 const SkImageFilter* filter, const SkIRect& subset,
1111 const SkIRect& clipBounds, SkIRect* outSubset,
1112 SkIPoint* offset) const;
1113
1114 /** To be deprecated.
1115 */
1116 sk_sp<SkImage> makeWithFilter(const SkImageFilter* filter, const SkIRect& subset,
1117 const SkIRect& clipBounds, SkIRect* outSubset,
1118 SkIPoint* offset) const;
1119
1120 /** Defines a callback function, taking one parameter of type GrBackendTexture with
1121 no return value. Function is called when back-end texture is to be released.
1122 */
1123 typedef std::function<void(GrBackendTexture)> BackendTextureReleaseProc;
1124
1125 /** Creates a GrBackendTexture from the provided SkImage. Returns true and
1126 stores result in backendTexture and backendTextureReleaseProc if
1127 texture is created; otherwise, returns false and leaves
1128 backendTexture and backendTextureReleaseProc unmodified.
1129
1130 Call backendTextureReleaseProc after deleting backendTexture.
1131 backendTextureReleaseProc cleans up auxiliary data related to returned
1132 backendTexture. The caller must delete returned backendTexture after use.
1133
1134 If SkImage is both texture backed and singly referenced, image is returned in
1135 backendTexture without conversion or making a copy. SkImage is singly referenced
1136 if its was transferred solely using std::move().
1137
1138 If SkImage is not texture backed, returns texture with SkImage contents.
1139
1140 @param context GPU context
1141 @param image SkImage used for texture
1142 @param backendTexture storage for back-end texture
1143 @param backendTextureReleaseProc storage for clean up function
1144 @return true if back-end texture was created
1145 */
1146 static bool MakeBackendTextureFromSkImage(GrContext* context,
1147 sk_sp<SkImage> image,
1148 GrBackendTexture* backendTexture,
1149 BackendTextureReleaseProc* backendTextureReleaseProc);
1150
1151 /** Deprecated.
1152 */
1153 enum LegacyBitmapMode {
1154 kRO_LegacyBitmapMode, //!< returned bitmap is read-only and immutable
1155 };
1156
1157 /** Deprecated.
1158 Creates raster SkBitmap with same pixels as SkImage. If legacyBitmapMode is
1159 kRO_LegacyBitmapMode, returned bitmap is read-only and immutable.
1160 Returns true if SkBitmap is stored in bitmap. Returns false and resets bitmap if
1161 SkBitmap write did not succeed.
1162
1163 @param bitmap storage for legacy SkBitmap
1164 @param legacyBitmapMode bitmap is read-only and immutable
1165 @return true if SkBitmap was created
1166 */
1167 bool asLegacyBitmap(SkBitmap* bitmap,
1168 LegacyBitmapMode legacyBitmapMode = kRO_LegacyBitmapMode) const;
1169
1170 /** Returns true if SkImage is backed by an image-generator or other service that creates
1171 and caches its pixels or texture on-demand.
1172
1173 @return true if SkImage is created as needed
1174
1175 example: https://fiddle.skia.org/c/@Image_isLazyGenerated_a
1176 example: https://fiddle.skia.org/c/@Image_isLazyGenerated_b
1177 */
1178 bool isLazyGenerated() const;
1179
1180 /** Creates SkImage in target SkColorSpace.
1181 Returns nullptr if SkImage could not be created.
1182
1183 Returns original SkImage if it is in target SkColorSpace.
1184 Otherwise, converts pixels from SkImage SkColorSpace to target SkColorSpace.
1185 If SkImage colorSpace() returns nullptr, SkImage SkColorSpace is assumed to be sRGB.
1186
1187 @param target SkColorSpace describing color range of returned SkImage
1188 @return created SkImage in target SkColorSpace
1189
1190 example: https://fiddle.skia.org/c/@Image_makeColorSpace
1191 */
1192 sk_sp<SkImage> makeColorSpace(sk_sp<SkColorSpace> target) const;
1193
1194 /** Experimental.
1195 Creates SkImage in target SkColorType and SkColorSpace.
1196 Returns nullptr if SkImage could not be created.
1197
1198 Returns original SkImage if it is in target SkColorType and SkColorSpace.
1199
1200 @param targetColorType SkColorType of returned SkImage
1201 @param targetColorSpace SkColorSpace of returned SkImage
1202 @return created SkImage in target SkColorType and SkColorSpace
1203 */
1204 sk_sp<SkImage> makeColorTypeAndColorSpace(SkColorType targetColorType,
1205 sk_sp<SkColorSpace> targetColorSpace) const;
1206
1207 /** Creates a new SkImage identical to this one, but with a different SkColorSpace.
1208 This does not convert the underlying pixel data, so the resulting image will draw
1209 differently.
1210 */
1211 sk_sp<SkImage> reinterpretColorSpace(sk_sp<SkColorSpace> newColorSpace) const;
1212
1213private:
1214 SkImage(const SkImageInfo& info, uint32_t uniqueID);
1215 friend class SkImage_Base;
1216
1217 SkImageInfo fInfo;
1218 const uint32_t fUniqueID;
1219
1220 typedef SkRefCnt INHERITED;
1221};
1222
1223#endif
1224