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 25 class SkData; 26 class SkCanvas; 27 class SkImageFilter; 28 class SkImageGenerator; 29 class SkPaint; 30 class SkPicture; 31 class SkSurface; 32 class GrBackendTexture; 33 class GrContext; 34 class GrContextThreadSafeProxy; 35 36 struct 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 */ 54 class SK_API SkImage : public SkRefCnt { 55 public: 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 */ MakeFromTexture(GrContext * context,const GrBackendTexture & backendTexture,GrSurfaceOrigin origin,SkColorType colorType,SkAlphaType alphaType,sk_sp<SkColorSpace> colorSpace)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 */ imageInfo()668 const SkImageInfo& imageInfo() const { return fInfo; } 669 670 /** Returns pixel count in each row. 671 672 @return pixel width in SkImage 673 */ width()674 int width() const { return fInfo.width(); } 675 676 /** Returns pixel row count. 677 678 @return pixel height in SkImage 679 */ height()680 int height() const { return fInfo.height(); } 681 682 /** Returns SkISize { width(), height() }. 683 684 @return integral size of width() and height() 685 */ dimensions()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 */ bounds()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 */ uniqueID()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 */ isOpaque()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; makeShader(SkTileMode tmx,SkTileMode tmy,const SkMatrix & localMatrix)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 } makeShader(const SkMatrix & localMatrix)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 1213 private: 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