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