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 "GrTypes.h" 12 #include "SkFilterQuality.h" 13 #include "SkImageInfo.h" 14 #include "SkImageEncoder.h" 15 #include "SkRefCnt.h" 16 #include "SkScalar.h" 17 #include "SkShader.h" 18 19 #if defined(SK_BUILD_FOR_ANDROID) && __ANDROID_API__ >= 26 20 #include <android/hardware_buffer.h> 21 #endif 22 23 class SkData; 24 class SkCanvas; 25 class SkImageFilter; 26 class SkImageGenerator; 27 class SkPaint; 28 class SkPicture; 29 class SkString; 30 class SkSurface; 31 class GrBackendTexture; 32 class GrContext; 33 class GrContextThreadSafeProxy; 34 class GrTexture; 35 36 /** \class SkImage 37 SkImage describes a two dimensional array of pixels to draw. The pixels may be 38 decoded in a raster bitmap, encoded in a SkPicture or compressed data stream, 39 or located in GPU memory as a GPU texture. 40 41 SkImage cannot be modified after it is created. SkImage may allocate additional 42 storage as needed; for instance, an encoded SkImage may decode when drawn. 43 44 SkImage width and height are greater than zero. Creating an SkImage with zero width 45 or height returns SkImage equal to nullptr. 46 47 SkImage may be created from SkBitmap, SkPixmap, SkSurface, SkPicture, encoded streams, 48 GPU texture, YUV_ColorSpace data, or hardware buffer. Encoded streams supported 49 include BMP, GIF, HEIF, ICO, JPEG, PNG, WBMP, WebP. Supported encoding details 50 vary with platform. 51 */ 52 class SK_API SkImage : public SkRefCnt { 53 public: 54 typedef SkImageInfo Info; 55 typedef void* ReleaseContext; 56 57 /** Creates SkImage from SkPixmap and copy of pixels. Since pixels are copied, SkPixmap 58 pixels may be modified or deleted without affecting SkImage. 59 60 SkImage is returned if SkPixmap is valid. Valid SkPixmap parameters include: 61 dimensions are greater than zero; 62 each dimension fits in 29 bits; 63 SkColorType and SkAlphaType are valid, and SkColorType is not kUnknown_SkColorType; 64 row bytes are large enough to hold one row of pixels; 65 pixel address is not nullptr. 66 67 @param pixmap SkImageInfo, pixel address, and row bytes 68 @return copy of SkPixmap pixels, or nullptr 69 */ 70 static sk_sp<SkImage> MakeRasterCopy(const SkPixmap& pixmap); 71 72 /** Creates SkImage from SkImageInfo, sharing pixels. 73 74 SkImage is returned if SkImageInfo is valid. Valid SkImageInfo parameters include: 75 dimensions are greater than zero; 76 each dimension fits in 29 bits; 77 SkColorType and SkAlphaType are valid, and SkColorType is not kUnknown_SkColorType; 78 rowBytes are large enough to hold one row of pixels; 79 pixels is not nullptr, and contains enough data for SkImage. 80 81 @param info contains width, height, SkAlphaType, SkColorType, SkColorSpace 82 @param pixels address or pixel storage 83 @param rowBytes size of pixel row or larger 84 @return SkImage sharing pixels, or nullptr 85 */ 86 static sk_sp<SkImage> MakeRasterData(const Info& info, sk_sp<SkData> pixels, size_t rowBytes); 87 88 typedef void (*RasterReleaseProc)(const void* pixels, ReleaseContext); 89 90 /** Creates SkImage from pixmap, sharing SkPixmap pixels. Pixels must remain valid and 91 unchanged until rasterReleaseProc is called. rasterReleaseProc is passed 92 releaseContext when SkImage is deleted or no longer refers to pixmap pixels. 93 94 Pass nullptr for rasterReleaseProc to share SkPixmap without requiring a callback 95 when SkImage is released. Pass nullptr for releaseContext if rasterReleaseProc 96 does not require state. 97 98 SkImage is returned if pixmap is valid. Valid SkPixmap parameters include: 99 dimensions are greater than zero; 100 each dimension fits in 29 bits; 101 SkColorType and SkAlphaType are valid, and SkColorType is not kUnknown_SkColorType; 102 row bytes are large enough to hold one row of pixels; 103 pixel address is not nullptr. 104 105 @param pixmap SkImageInfo, pixel address, and row bytes 106 @param rasterReleaseProc function called when pixels can be released; or nullptr 107 @param releaseContext state passed to rasterReleaseProc; or nullptr 108 @return SkImage sharing pixmap 109 */ 110 static sk_sp<SkImage> MakeFromRaster(const SkPixmap& pixmap, 111 RasterReleaseProc rasterReleaseProc, 112 ReleaseContext releaseContext); 113 114 /** Creates SkImage from bitmap, sharing or copying bitmap pixels. If the bitmap 115 is marked immutable, and its pixel memory is shareable, it may be shared 116 instead of copied. 117 118 SkImage is returned if bitmap is valid. Valid SkBitmap parameters include: 119 dimensions are greater than zero; 120 each dimension fits in 29 bits; 121 SkColorType and SkAlphaType are valid, and SkColorType is not kUnknown_SkColorType; 122 row bytes are large enough to hold one row of pixels; 123 pixel address is not nullptr. 124 125 @param bitmap SkImageInfo, row bytes, and pixels 126 @return created SkImage, or nullptr 127 */ 128 static sk_sp<SkImage> MakeFromBitmap(const SkBitmap& bitmap); 129 130 /** Creates SkImage from data returned by imageGenerator. Generated data is owned by SkImage and may not 131 be shared or accessed. 132 133 subset allows selecting a portion of the full image. Pass nullptr to select the entire image; 134 otherwise, subset must be contained by image bounds. 135 136 SkImage is returned if generator data is valid. Valid data parameters vary by type of data 137 and platform. 138 139 imageGenerator may wrap SkPicture data, codec data, or custom data. 140 141 @param imageGenerator stock or custom routines to retrieve SkImage 142 @param subset bounds of returned SkImage; may be nullptr 143 @return created SkImage, or nullptr 144 */ 145 static sk_sp<SkImage> MakeFromGenerator(std::unique_ptr<SkImageGenerator> imageGenerator, 146 const SkIRect* subset = nullptr); 147 148 /** Creates SkImage from encoded data. 149 subset allows selecting a portion of the full image. Pass nullptr to select the entire image; 150 otherwise, subset must be contained by image bounds. 151 152 SkImage is returned if format of the encoded data is recognized and supported. 153 Recognized formats vary by platform. 154 155 @param encoded data of SkImage to decode 156 @param subset bounds of returned SkImage; may be nullptr 157 @return created SkImage, or nullptr 158 */ 159 static sk_sp<SkImage> MakeFromEncoded(sk_sp<SkData> encoded, const SkIRect* subset = nullptr); 160 161 typedef void (*TextureReleaseProc)(ReleaseContext releaseContext); 162 163 /** Deprecated. 164 */ 165 static sk_sp<SkImage> MakeFromTexture(GrContext* context, 166 const GrBackendTexture& backendTexture, 167 GrSurfaceOrigin origin, 168 SkAlphaType alphaType, 169 sk_sp<SkColorSpace> colorSpace) { 170 return MakeFromTexture(context, backendTexture, origin, alphaType, colorSpace, nullptr, 171 nullptr); 172 } 173 174 /** Deprecated. 175 */ 176 static sk_sp<SkImage> MakeFromTexture(GrContext* context, 177 const GrBackendTexture& backendTexture, 178 GrSurfaceOrigin origin, 179 SkAlphaType alphaType, 180 sk_sp<SkColorSpace> colorSpace, 181 TextureReleaseProc textureReleaseProc, 182 ReleaseContext releaseContext); 183 184 /** Creates SkImage from GPU texture associated with context. Caller is responsible for 185 managing the lifetime of GPU texture. 186 187 SkImage is returned if format of backendTexture is recognized and supported. 188 Recognized formats vary by GPU back-end. 189 190 @param context GPU context 191 @param backendTexture texture residing on GPU 192 @param origin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin 193 @param colorType one of: kUnknown_SkColorType, kAlpha_8_SkColorType, 194 kRGB_565_SkColorType, kARGB_4444_SkColorType, 195 kRGBA_8888_SkColorType, kBGRA_8888_SkColorType, 196 kGray_8_SkColorType, kRGBA_F16_SkColorType 197 @param alphaType one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType, 198 kPremul_SkAlphaType, kUnpremul_SkAlphaType 199 @param colorSpace range of colors; may be nullptr 200 @return created SkImage, or nullptr 201 */ 202 static sk_sp<SkImage> MakeFromTexture(GrContext* context, 203 const GrBackendTexture& backendTexture, 204 GrSurfaceOrigin origin, 205 SkColorType colorType, 206 SkAlphaType alphaType, 207 sk_sp<SkColorSpace> colorSpace) { 208 return MakeFromTexture(context, backendTexture, origin, colorType, alphaType, colorSpace, 209 nullptr, nullptr); 210 } 211 212 /** Creates SkImage from GPU texture associated with context. GPU texture must stay 213 valid and unchanged until textureReleaseProc is called. textureReleaseProc is 214 passed releaseContext when SkImage is deleted or no longer refers to texture. 215 216 SkImage is returned if format of backendTexture is recognized and supported. 217 Recognized formats vary by GPU back-end. 218 219 @param context GPU context 220 @param backendTexture texture residing on GPU 221 @param origin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin 222 @param colorType one of: kUnknown_SkColorType, kAlpha_8_SkColorType, 223 kRGB_565_SkColorType, kARGB_4444_SkColorType, 224 kRGBA_8888_SkColorType, kBGRA_8888_SkColorType, 225 kGray_8_SkColorType, kRGBA_F16_SkColorType 226 @param alphaType one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType, 227 kPremul_SkAlphaType, kUnpremul_SkAlphaType 228 @param colorSpace range of colors; may be nullptr 229 @param textureReleaseProc function called when texture can be released 230 @param releaseContext state passed to textureReleaseProc 231 @return created SkImage, or nullptr 232 */ 233 static sk_sp<SkImage> MakeFromTexture(GrContext* context, 234 const GrBackendTexture& backendTexture, 235 GrSurfaceOrigin origin, 236 SkColorType colorType, 237 SkAlphaType alphaType, 238 sk_sp<SkColorSpace> colorSpace, 239 TextureReleaseProc textureReleaseProc, 240 ReleaseContext releaseContext); 241 242 /** Creates SkImage from encoded data. SkImage is uploaded to GPU back-end using context. 243 244 Created SkImage is available to other GPU contexts, and is available across thread 245 boundaries. All contexts must be in the same GPU_Share_Group, or otherwise 246 share resources. 247 248 When SkImage is no longer referenced, context releases texture memory 249 asynchronously. 250 251 GrBackendTexture decoded from data is uploaded to match SkSurface created with 252 dstColorSpace. SkColorSpace of SkImage is determined by encoded data. 253 254 SkImage is returned if format of data is recognized and supported, and if context 255 supports moving resources. Recognized formats vary by platform and GPU back-end. 256 257 SkImage is returned using MakeFromEncoded() if context is nullptr or does not support 258 moving resources between contexts. 259 260 @param context GPU context 261 @param data SkImage to decode 262 @param buildMips create SkImage as Mip_Map if true 263 @param dstColorSpace range of colors of matching SkSurface on GPU 264 @return created SkImage, or nullptr 265 */ 266 static sk_sp<SkImage> MakeCrossContextFromEncoded(GrContext* context, sk_sp<SkData> data, 267 bool buildMips, SkColorSpace* dstColorSpace); 268 269 /** Creates SkImage from pixmap. SkImage is uploaded to GPU back-end using context. 270 271 Created SkImage is available to other GPU contexts, and is available across thread 272 boundaries. All contexts must be in the same GPU_Share_Group, or otherwise 273 share resources. 274 275 When SkImage is no longer referenced, context releases texture memory 276 asynchronously. 277 278 GrBackendTexture created from pixmap is uploaded to match SkSurface created with 279 dstColorSpace. SkColorSpace of SkImage is determined by pixmap.colorSpace(). 280 281 SkImage is returned referring to GPU back-end if context is not nullptr, 282 format of data is recognized and supported, and if context supports moving 283 resources between contexts. Otherwise, pixmap pixel data is copied and SkImage 284 as returned in raster format if possible; nullptr may be returned. 285 Recognized GPU formats vary by platform and GPU back-end. 286 287 @param context GPU context 288 @param pixmap SkImageInfo, pixel address, and row bytes 289 @param buildMips create SkImage as Mip_Map if true 290 @param dstColorSpace range of colors of matching SkSurface on GPU 291 @return created SkImage, or nullptr 292 */ 293 static sk_sp<SkImage> MakeCrossContextFromPixmap(GrContext* context, const SkPixmap& pixmap, 294 bool buildMips, SkColorSpace* dstColorSpace); 295 296 /** Deprecated. 297 */ 298 static sk_sp<SkImage> MakeFromAdoptedTexture(GrContext* context, 299 const GrBackendTexture& backendTexture, 300 GrSurfaceOrigin surfaceOrigin, 301 SkAlphaType alphaType = kPremul_SkAlphaType, 302 sk_sp<SkColorSpace> colorSpace = nullptr); 303 304 /** Creates SkImage from backendTexture associated with context. backendTexture and 305 returned SkImage are managed internally, and are released when no longer needed. 306 307 SkImage is returned if format of backendTexture is recognized and supported. 308 Recognized formats vary by GPU back-end. 309 310 @param context GPU context 311 @param backendTexture texture residing on GPU 312 @param surfaceOrigin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin 313 @param colorType one of: kUnknown_SkColorType, kAlpha_8_SkColorType, 314 kRGB_565_SkColorType, kARGB_4444_SkColorType, 315 kRGBA_8888_SkColorType, kBGRA_8888_SkColorType, 316 kGray_8_SkColorType, kRGBA_F16_SkColorType 317 @param alphaType one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType, 318 kPremul_SkAlphaType, kUnpremul_SkAlphaType 319 @param colorSpace range of colors; may be nullptr 320 @return created SkImage, or nullptr 321 */ 322 static sk_sp<SkImage> MakeFromAdoptedTexture(GrContext* context, 323 const GrBackendTexture& backendTexture, 324 GrSurfaceOrigin surfaceOrigin, 325 SkColorType colorType, 326 SkAlphaType alphaType = kPremul_SkAlphaType, 327 sk_sp<SkColorSpace> colorSpace = nullptr); 328 329 /** Creates SkImage from copy of yuvTextureHandles, an array of textures on GPU. 330 yuvTextureHandles contain pixels for YUV planes of SkImage. 331 yuvSizes contain dimensions for each pixel plane. Dimensions must be greater than 332 zero but may differ from plane to plane. Returned SkImage has the dimensions 333 yuvSizes[0]. yuvColorSpace describes how YUV colors convert to RGB colors. 334 335 @param context GPU context 336 @param yuvColorSpace one of: kJPEG_SkYUVColorSpace, kRec601_SkYUVColorSpace, 337 kRec709_SkYUVColorSpace 338 @param yuvTextureHandles array of YUV textures on GPU 339 @param yuvSizes dimensions of YUV textures 340 @param surfaceOrigin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin 341 @param colorSpace range of colors; may be nullptr 342 @return created SkImage, or nullptr 343 */ 344 static sk_sp<SkImage> MakeFromYUVTexturesCopy(GrContext* context, SkYUVColorSpace yuvColorSpace, 345 const GrBackendObject yuvTextureHandles[3], 346 const SkISize yuvSizes[3], 347 GrSurfaceOrigin surfaceOrigin, 348 sk_sp<SkColorSpace> colorSpace = nullptr); 349 350 /** Creates SkImage from copy of nv12TextureHandles, an array of textures on GPU. 351 nv12TextureHandles[0] contains pixels for YUV_Component_Y plane. 352 nv12TextureHandles[1] contains pixels for YUV_Component_U plane, 353 followed by pixels for YUV_Component_V plane. 354 nv12Sizes contain dimensions for each pixel plane. Dimensions must be greater than 355 zero but may differ from plane to plane. Returned SkImage has the dimensions 356 nv12Sizes[0]. yuvColorSpace describes how YUV colors convert to RGB colors. 357 358 @param context GPU context 359 @param yuvColorSpace one of: kJPEG_SkYUVColorSpace, kRec601_SkYUVColorSpace, 360 kRec709_SkYUVColorSpace 361 @param nv12TextureHandles array of YUV textures on GPU 362 @param nv12Sizes dimensions of YUV textures 363 @param surfaceOrigin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin 364 @param colorSpace range of colors; may be nullptr 365 @return created SkImage, or nullptr 366 */ 367 static sk_sp<SkImage> MakeFromNV12TexturesCopy(GrContext* context, 368 SkYUVColorSpace yuvColorSpace, 369 const GrBackendObject nv12TextureHandles[2], 370 const SkISize nv12Sizes[2], 371 GrSurfaceOrigin surfaceOrigin, 372 sk_sp<SkColorSpace> colorSpace = nullptr); 373 374 /** Creates SkImage from copy of yuvTextureHandles, an array of textures on GPU. 375 yuvTextureHandles contain pixels for YUV planes of SkImage. 376 yuvSizes contain dimensions for each pixel plane. Dimensions must be greater than 377 zero but may differ from plane to plane. Returned SkImage has the dimensions 378 yuvSizes[0]. yuvColorSpace describes how YUV colors convert to RGB colors. 379 380 @param context GPU context 381 @param yuvColorSpace one of: kJPEG_SkYUVColorSpace, kRec601_SkYUVColorSpace, 382 kRec709_SkYUVColorSpace 383 @param yuvTextureHandles array of YUV textures on GPU 384 @param yuvSizes dimensions of YUV textures 385 @param surfaceOrigin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin 386 @param colorSpace range of colors; may be nullptr 387 @return created SkImage, or nullptr 388 */ 389 static sk_sp<SkImage> MakeFromYUVTexturesCopy(GrContext* context, SkYUVColorSpace yuvColorSpace, 390 const GrBackendTexture yuvTextureHandles[3], 391 const SkISize yuvSizes[3], 392 GrSurfaceOrigin surfaceOrigin, 393 sk_sp<SkColorSpace> colorSpace = nullptr); 394 395 /** Creates SkImage from copy of nv12TextureHandles, an array of textures on GPU. 396 nv12TextureHandles[0] contains pixels for YUV_Component_Y plane. 397 nv12TextureHandles[1] contains pixels for YUV_Component_U plane, 398 followed by pixels for YUV_Component_V plane. 399 nv12Sizes contain dimensions for each pixel plane. Dimensions must be greater than 400 zero but may differ from plane to plane. Returned SkImage has the dimensions 401 nv12Sizes[0]. yuvColorSpace describes how YUV colors convert to RGB colors. 402 403 @param context GPU context 404 @param yuvColorSpace one of: kJPEG_SkYUVColorSpace, kRec601_SkYUVColorSpace, 405 kRec709_SkYUVColorSpace 406 @param nv12TextureHandles array of YUV textures on GPU 407 @param nv12Sizes dimensions of YUV textures 408 @param surfaceOrigin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin 409 @param colorSpace range of colors; may be nullptr 410 @return created SkImage, or nullptr 411 */ 412 static sk_sp<SkImage> MakeFromNV12TexturesCopy(GrContext* context, 413 SkYUVColorSpace yuvColorSpace, 414 const GrBackendTexture nv12TextureHandles[2], 415 const SkISize nv12Sizes[2], 416 GrSurfaceOrigin surfaceOrigin, 417 sk_sp<SkColorSpace> colorSpace = nullptr); 418 419 enum class BitDepth { 420 kU8, //!< Use 8 bits per ARGB component using unsigned integer format. 421 kF16, //!< Use 16 bits per ARGB component using half-precision floating point format. 422 }; 423 424 /** Creates SkImage from picture. Returned SkImage width and height are set by dimensions. 425 SkImage draws picture with matrix and paint, set to bitDepth and colorSpace. 426 427 If matrix is nullptr, draws with identity SkMatrix. If paint is nullptr, draws 428 with default SkPaint. colorSpace may be nullptr. 429 430 @param picture stream of drawing commands 431 @param dimensions width and height 432 @param matrix SkMatrix to rotate, scale, translate, and so on; may be nullptr 433 @param paint SkPaint to apply transparency, filtering, and so on; may be nullptr 434 @param bitDepth 8 bit integer or 16 bit float: per component 435 @param colorSpace range of colors; may be nullptr 436 @return created SkImage, or nullptr 437 */ 438 static sk_sp<SkImage> MakeFromPicture(sk_sp<SkPicture> picture, const SkISize& dimensions, 439 const SkMatrix* matrix, const SkPaint* paint, 440 BitDepth bitDepth, 441 sk_sp<SkColorSpace> colorSpace); 442 443 #if defined(SK_BUILD_FOR_ANDROID) && __ANDROID_API__ >= 26 444 /** (see skbug.com/7447) 445 Creates SkImage from Android hardware buffer. 446 Returned SkImage takes a reference on the buffer. 447 448 Only available on Android, when __ANDROID_API__ is defined to be 26 or greater. 449 450 @param hardwareBuffer AHardwareBuffer Android hardware buffer 451 @param alphaType one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType, 452 kPremul_SkAlphaType, kUnpremul_SkAlphaType 453 @param colorSpace range of colors; may be nullptr 454 @return created SkImage, or nullptr 455 */ 456 static sk_sp<SkImage> MakeFromAHardwareBuffer(AHardwareBuffer* hardwareBuffer, 457 SkAlphaType alphaType = kPremul_SkAlphaType, 458 sk_sp<SkColorSpace> colorSpace = nullptr); 459 #endif 460 461 /** Returns pixel count in each row. 462 463 @return pixel width in SkImage 464 */ 465 int width() const { return fWidth; } 466 467 /** Returns pixel row count. 468 469 @return pixel height in SkImage 470 */ 471 int height() const { return fHeight; } 472 473 /** Returns SkISize { width(), height() }. 474 475 @return integral size of width() and height() 476 */ 477 SkISize dimensions() const { return SkISize::Make(fWidth, fHeight); } 478 479 /** Returns SkIRect { 0, 0, width(), height() }. 480 481 @return integral rectangle from origin to width() and height() 482 */ 483 SkIRect bounds() const { return SkIRect::MakeWH(fWidth, fHeight); } 484 485 /** Returns value unique to image. SkImage contents cannot change after SkImage is 486 created. Any operation to create a new SkImage will receive generate a new 487 unique number. 488 489 @return unique identifier 490 */ 491 uint32_t uniqueID() const { return fUniqueID; } 492 493 /** Returns SkAlphaType, one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType, 494 kPremul_SkAlphaType, kUnpremul_SkAlphaType. 495 496 SkAlphaType returned was a parameter to an SkImage constructor, 497 or was parsed from encoded data. 498 499 @return SkAlphaType in SkImage 500 */ 501 SkAlphaType alphaType() const; 502 503 /** Returns SkColorSpace, the range of colors, associated with SkImage. The 504 reference count of SkColorSpace is unchanged. The returned SkColorSpace is 505 immutable. 506 507 SkColorSpace returned was passed to an SkImage constructor, 508 or was parsed from encoded data. SkColorSpace returned may be ignored when SkImage 509 is drawn, depending on the capabilities of the SkSurface receiving the drawing. 510 511 @return SkColorSpace in SkImage, or nullptr 512 */ 513 SkColorSpace* colorSpace() const; 514 515 /** Returns a smart pointer to SkColorSpace, the range of colors, associated with 516 SkImage. The smart pointer tracks the number of objects sharing this 517 SkColorSpace reference so the memory is released when the owners destruct. 518 519 The returned SkColorSpace is immutable. 520 521 SkColorSpace returned was passed to an SkImage constructor, 522 or was parsed from encoded data. SkColorSpace returned may be ignored when SkImage 523 is drawn, depending on the capabilities of the SkSurface receiving the drawing. 524 525 @return SkColorSpace in SkImage, or nullptr, wrapped in a smart pointer 526 */ 527 sk_sp<SkColorSpace> refColorSpace() const; 528 529 /** Returns true if SkImage pixels represent transparency only. If true, each pixel 530 is packed in 8 bits as defined by kAlpha_8_SkColorType. 531 532 @return true if pixels represent a transparency mask 533 */ 534 bool isAlphaOnly() const; 535 536 /** Returns true if pixels ignore their alpha value and are treated as fully opaque. 537 538 @return true if SkAlphaType is kOpaque_SkAlphaType 539 */ 540 bool isOpaque() const { return SkAlphaTypeIsOpaque(this->alphaType()); } 541 542 /** Creates SkShader from SkImage. SkShader dimensions are taken from SkImage. SkShader uses 543 SkShader::TileMode rules to fill drawn area outside SkImage. localMatrix permits 544 transforming SkImage before SkCanvas matrix is applied. 545 546 @param tileMode1 tiling in x, one of: SkShader::kClamp_TileMode, SkShader::kRepeat_TileMode, 547 SkShader::kMirror_TileMode 548 @param tileMode2 tiling in y, one of: SkShader::kClamp_TileMode, SkShader::kRepeat_TileMode, 549 SkShader::kMirror_TileMode 550 @param localMatrix SkImage transformation, or nullptr 551 @return SkShader containing SkImage 552 */ 553 sk_sp<SkShader> makeShader(SkShader::TileMode tileMode1, SkShader::TileMode tileMode2, 554 const SkMatrix* localMatrix = nullptr) const; 555 556 /** Creates SkShader from SkImage. SkShader dimensions are taken from SkImage. SkShader uses 557 SkShader::kClamp_TileMode to fill drawn area outside SkImage. localMatrix permits 558 transforming SkImage before SkCanvas matrix is applied. 559 560 @param localMatrix SkImage transformation, or nullptr 561 @return SkShader containing SkImage 562 */ 563 sk_sp<SkShader> makeShader(const SkMatrix* localMatrix = nullptr) const { 564 return this->makeShader(SkShader::kClamp_TileMode, SkShader::kClamp_TileMode, localMatrix); 565 } 566 567 /** Copies SkImage pixel address, row bytes, and SkImageInfo to pixmap, if address 568 is available, and returns true. If pixel address is not available, return 569 false and leave pixmap unchanged. 570 571 @param pixmap storage for pixel state if pixels are readable; otherwise, ignored 572 @return true if SkImage has direct access to pixels 573 */ 574 bool peekPixels(SkPixmap* pixmap) const; 575 576 /** Deprecated. 577 */ 578 GrTexture* getTexture() const; 579 580 /** Returns true the contents of SkImage was created on or uploaded to GPU memory, 581 and is available as a GPU texture. 582 583 @return true if SkImage is a GPU texture 584 */ 585 bool isTextureBacked() const; 586 587 /** Returns true if SkImage can be drawn on either raster surface or GPU surface. 588 If context is nullptr, tests if SkImage draws on raster surface; 589 otherwise, tests if SkImage draws on GPU surface associated with context. 590 591 SkImage backed by GPU texture may become invalid if associated GrContext is 592 invalid. lazy image may be invalid and may not draw to raster surface or 593 GPU surface or both. 594 595 @param context GPU context 596 @return true if SkImage can be drawn 597 */ 598 bool isValid(GrContext* context) const; 599 600 /** Retrieves the back-end API handle of texture. If flushPendingGrContextIO is true, 601 complete deferred I/O operations. 602 603 If origin in not nullptr, copies location of content drawn into SkImage. 604 605 @param flushPendingGrContextIO flag to flush outstanding requests 606 @param origin storage for one of: kTopLeft_GrSurfaceOrigin, 607 kBottomLeft_GrSurfaceOrigin; or nullptr 608 @return back-end API texture handle, or nullptr 609 */ 610 GrBackendObject getTextureHandle(bool flushPendingGrContextIO, 611 GrSurfaceOrigin* origin = nullptr) const; 612 613 /** \enum SkImage::CachingHint 614 CachingHint selects whether Skia may internally cache SkBitmap generated by 615 decoding SkImage, or by copying SkImage from GPU to CPU. The default behavior 616 allows caching SkBitmap. 617 618 Choose kDisallow_CachingHint if SkImage pixels are to be used only once, or 619 if SkImage pixels reside in a cache outside of Skia, or to reduce memory pressure. 620 621 Choosing kAllow_CachingHint does not ensure that pixels will be cached. 622 SkImage pixels may not be cached if memory requirements are too large or 623 pixels are not accessible. 624 */ 625 enum CachingHint { 626 kAllow_CachingHint, //!< Allows Skia to internally cache decoded and copied pixels. 627 628 /** Disallows Skia from internally caching decoded and copied pixels. */ 629 kDisallow_CachingHint, 630 }; 631 632 /** Copies SkRect of pixels from SkImage to dstPixels. Copy starts at offset (srcX, srcY), 633 and does not exceed SkImage (width(), height()). 634 635 dstInfo specifies width, height, SkColorType, SkAlphaType, and SkColorSpace of 636 destination. dstRowBytes specifics the gap from one destination row to the next. 637 Returns true if pixels are copied. Returns false if: 638 - dstInfo.addr() equals nullptr 639 - dstRowBytes is less than dstInfo.minRowBytes() 640 - SkPixelRef is nullptr 641 642 Pixels are copied only if pixel conversion is possible. If SkImage SkColorType is 643 kGray_8_SkColorType, or kAlpha_8_SkColorType; dstInfo.colorType() must match. 644 If SkImage SkColorType is kGray_8_SkColorType, dstInfo.colorSpace() must match. 645 If SkImage SkAlphaType is kOpaque_SkAlphaType, dstInfo.alphaType() must 646 match. If SkImage SkColorSpace is nullptr, dstInfo.colorSpace() must match. Returns 647 false if pixel conversion is not possible. 648 649 srcX and srcY may be negative to copy only top or left of source. Returns 650 false if width() or height() is zero or negative. 651 Returns false if abs(srcX) >= Image width(), or if abs(srcY) >= Image height(). 652 653 If cachingHint is kAllow_CachingHint, pixels may be retained locally. 654 If cachingHint is kDisallow_CachingHint, pixels are not added to the local cache. 655 656 @param dstInfo destination width, height, SkColorType, SkAlphaType, SkColorSpace 657 @param dstPixels destination pixel storage 658 @param dstRowBytes destination row length 659 @param srcX column index whose absolute value is less than width() 660 @param srcY row index whose absolute value is less than height() 661 @param cachingHint one of: kAllow_CachingHint, kDisallow_CachingHint 662 @return true if pixels are copied to dstPixels 663 */ 664 bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes, 665 int srcX, int srcY, CachingHint cachingHint = kAllow_CachingHint) const; 666 667 /** Copies a SkRect of pixels from SkImage to dst. Copy starts at (srcX, srcY), and 668 does not exceed SkImage (width(), height()). 669 670 dst specifies width, height, SkColorType, SkAlphaType, SkColorSpace, pixel storage, 671 and row bytes of destination. dst.rowBytes() specifics the gap from one destination 672 row to the next. Returns true if pixels are copied. Returns false if: 673 - dst pixel storage equals nullptr 674 - dst.rowBytes is less than SkImageInfo::minRowBytes 675 - SkPixelRef is nullptr 676 677 Pixels are copied only if pixel conversion is possible. If SkImage SkColorType is 678 kGray_8_SkColorType, or kAlpha_8_SkColorType; dst.colorType() must match. 679 If SkImage SkColorType is kGray_8_SkColorType, dst.colorSpace() must match. 680 If SkImage SkAlphaType is kOpaque_SkAlphaType, dst.alphaType() must 681 match. If SkImage SkColorSpace is nullptr, dst.colorSpace() must match. Returns 682 false if pixel conversion is not possible. 683 684 srcX and srcY may be negative to copy only top or left of source. Returns 685 false if width() or height() is zero or negative. 686 Returns false if abs(srcX) >= Image width(), or if abs(srcY) >= Image height(). 687 688 If cachingHint is kAllow_CachingHint, pixels may be retained locally. 689 If cachingHint is kDisallow_CachingHint, pixels are not added to the local cache. 690 691 @param dst destination SkPixmap: SkImageInfo, pixels, row bytes 692 @param srcX column index whose absolute value is less than width() 693 @param srcY row index whose absolute value is less than height() 694 @param cachingHint one of: kAllow_CachingHint, kDisallow_CachingHint 695 @return true if pixels are copied to dst 696 */ 697 bool readPixels(const SkPixmap& dst, int srcX, int srcY, 698 CachingHint cachingHint = kAllow_CachingHint) const; 699 700 /** Copies SkImage to dst, scaling pixels to fit dst.width() and dst.height(), and 701 converting pixels to match dst.colorType() and dst.alphaType(). Returns true if 702 pixels are copied. Returns false if dst.addr() is nullptr, or dst.rowBytes() is 703 less than dst SkImageInfo::minRowBytes. 704 705 Pixels are copied only if pixel conversion is possible. If SkImage SkColorType is 706 kGray_8_SkColorType, or kAlpha_8_SkColorType; dst.colorType() must match. 707 If SkImage SkColorType is kGray_8_SkColorType, dst.colorSpace() must match. 708 If SkImage SkAlphaType is kOpaque_SkAlphaType, dst.alphaType() must 709 match. If SkImage SkColorSpace is nullptr, dst.colorSpace() must match. Returns 710 false if pixel conversion is not possible. 711 712 Scales the image, with filterQuality, to match dst.width() and dst.height(). 713 filterQuality kNone_SkFilterQuality is fastest, typically implemented with 714 nearest neighbor filter. kLow_SkFilterQuality is typically implemented with 715 bilerp filter. kMedium_SkFilterQuality is typically implemented with 716 bilerp filter, and Filter_Quality_MipMap when size is reduced. 717 kHigh_SkFilterQuality is slowest, typically implemented with Filter_Quality_BiCubic. 718 719 If cachingHint is kAllow_CachingHint, pixels may be retained locally. 720 If cachingHint is kDisallow_CachingHint, pixels are not added to the local cache. 721 722 @param dst destination SkPixmap: SkImageInfo, pixels, row bytes 723 @param filterQuality one of: kNone_SkFilterQuality, kLow_SkFilterQuality, 724 kMedium_SkFilterQuality, kHigh_SkFilterQuality 725 @param cachingHint one of: kAllow_CachingHint, kDisallow_CachingHint 726 @return true if pixels are scaled to fit dst 727 */ 728 bool scalePixels(const SkPixmap& dst, SkFilterQuality filterQuality, 729 CachingHint cachingHint = kAllow_CachingHint) const; 730 731 /** Encodes SkImage pixels, returning result as SkData. 732 733 Returns nullptr if encoding fails, or if encodedImageFormat is not supported. 734 735 SkImage encoding in a format requires both building with one or more of: 736 SK_HAS_JPEG_LIBRARY, SK_HAS_PNG_LIBRARY, SK_HAS_WEBP_LIBRARY; and platform support 737 for the encoded format. 738 739 If SK_BUILD_FOR_MAC or SK_BUILD_FOR_IOS is defined, encodedImageFormat can 740 additionally be one of: SkEncodedImageFormat::kICO, SkEncodedImageFormat::kBMP, 741 SkEncodedImageFormat::kGIF. 742 743 quality is a platform and format specific metric trading off size and encoding 744 error. When used, quality equaling 100 encodes with the least error. quality may 745 be ignored by the encoder. 746 747 @param encodedImageFormat one of: SkEncodedImageFormat::kJPEG, SkEncodedImageFormat::kPNG, 748 SkEncodedImageFormat::kWEBP 749 @param quality encoder specific metric with 100 equaling best 750 @return encoded SkImage, or nullptr 751 */ 752 sk_sp<SkData> encodeToData(SkEncodedImageFormat encodedImageFormat, int quality) const; 753 754 /** Encodes SkImage pixels, returning result as SkData. Returns existing encoded data 755 if present; otherwise, SkImage is encoded with SkEncodedImageFormat::kPNG. Skia 756 must be built with SK_HAS_PNG_LIBRARY to encode SkImage. 757 758 Returns nullptr if existing encoded data is missing or invalid, and 759 encoding fails. 760 761 @return encoded SkImage, or nullptr 762 */ 763 sk_sp<SkData> encodeToData() const; 764 765 /** Returns encoded SkImage pixels as SkData, if SkImage was created from supported 766 encoded stream format. Platform support for formats vary and may require building 767 with one or more of: SK_HAS_JPEG_LIBRARY, SK_HAS_PNG_LIBRARY, SK_HAS_WEBP_LIBRARY. 768 769 Returns nullptr if SkImage contents are not encoded. 770 771 @return encoded SkImage, or nullptr 772 */ 773 sk_sp<SkData> refEncodedData() const; 774 775 /** Appends SkImage description to string, including unique ID, width, height, and 776 whether the image is opaque. 777 778 @param string storage for description; existing content is preserved 779 @return string appended with SkImage description 780 */ 781 const char* toString(SkString* string) const; 782 783 /** Returns subset of SkImage. subset must be fully contained by SkImage dimensions(). 784 The implementation may share pixels, or may copy them. 785 786 Returns nullptr if subset is empty, or subset is not contained by bounds, or 787 pixels in SkImage could not be read or copied. 788 789 @param subset bounds of returned SkImage 790 @return partial or full SkImage, or nullptr 791 */ 792 sk_sp<SkImage> makeSubset(const SkIRect& subset) const; 793 794 /** Returns SkImage backed by GPU texture associated with context. Returned SkImage is 795 compatible with SkSurface created with dstColorSpace. Returns original 796 SkImage if context and dstColorSpace match. 797 798 Returns nullptr if context is nullptr, or if SkImage was created with another 799 GrContext. 800 801 @param context GPU context 802 @param dstColorSpace range of colors of matching SkSurface on GPU 803 @return created SkImage, or nullptr 804 */ 805 sk_sp<SkImage> makeTextureImage(GrContext* context, SkColorSpace* dstColorSpace) const; 806 807 /** Returns raster image or lazy image. Copies SkImage backed by GPU texture into 808 CPU memory if needed. Returns original SkImage if decoded in raster bitmap, 809 or if encoded in a stream. 810 811 Returns nullptr if backed by GPU texture and copy fails. 812 813 @return raster image, lazy image, or nullptr 814 */ 815 sk_sp<SkImage> makeNonTextureImage() const; 816 817 /** Returns raster image. Copies SkImage backed by GPU texture into CPU memory, 818 or decodes SkImage from lazy image. Returns original SkImage if decoded in 819 raster bitmap. 820 821 Returns nullptr if copy, decode, or pixel read fails. 822 823 @return raster image, or nullptr 824 */ 825 sk_sp<SkImage> makeRasterImage() const; 826 827 /** Creates filtered SkImage. filter processes original SkImage, potentially changing 828 color, position, and size. subset is the bounds of original SkImage processed 829 by filter. clipBounds is the expected bounds of the filtered SkImage. outSubset 830 is required storage for the actual bounds of the filtered SkImage. offset is 831 required storage for translation of returned SkImage. 832 833 Returns nullptr if SkImage could not be created. If nullptr is returned, outSubset 834 and offset are undefined. 835 836 Useful for animation of SkImageFilter that varies size from frame to frame. 837 Returned SkImage is created larger than required by filter so that GPU texture 838 can be reused with different sized effects. outSubset describes the valid bounds 839 of GPU texture returned. offset translates the returned SkImage to keep subsequent 840 animation frames aligned with respect to each other. 841 842 @param filter how SkImage is sampled when transformed 843 @param subset bounds of SkImage processed by filter 844 @param clipBounds expected bounds of filtered SkImage 845 @param outSubset storage for returned SkImage bounds 846 @param offset storage for returned SkImage translation 847 @return filtered SkImage, or nullptr 848 */ 849 sk_sp<SkImage> makeWithFilter(const SkImageFilter* filter, const SkIRect& subset, 850 const SkIRect& clipBounds, SkIRect* outSubset, 851 SkIPoint* offset) const; 852 853 typedef std::function<void(GrBackendTexture)> BackendTextureReleaseProc; 854 855 /** Creates a GrBackendTexture from the provided SkImage. Returns true and 856 stores result in backendTexture and backendTextureReleaseProc if 857 texture is created; otherwise, returns false and leaves 858 backendTexture and backendTextureReleaseProc unmodified. 859 860 Call backendTextureReleaseProc after deleting backendTexture. 861 backendTextureReleaseProc cleans up auxiliary data related to returned 862 backendTexture. The caller must delete returned backendTexture after use. 863 864 If SkImage is both texture backed and singly referenced, image is returned in 865 backendTexture without conversion or making a copy. SkImage is singly referenced 866 if its was transferred solely using std::move(). 867 868 If SkImage is not texture backed, returns texture with SkImage contents. 869 870 @param context GPU context 871 @param image SkImage used for texture 872 @param backendTexture storage for backend texture 873 @param backendTextureReleaseProc storage for clean up function 874 @return true if backend texture was created 875 */ 876 static bool MakeBackendTextureFromSkImage(GrContext* context, 877 sk_sp<SkImage> image, 878 GrBackendTexture* backendTexture, 879 BackendTextureReleaseProc* backendTextureReleaseProc); 880 881 enum LegacyBitmapMode { 882 kRO_LegacyBitmapMode, //!< Returned bitmap is read-only and immutable. 883 }; 884 885 /** Creates raster SkBitmap with same pixels as SkImage. If legacyBitmapMode is 886 kRO_LegacyBitmapMode, returned bitmap is read-only and immutable. 887 Returns true if SkBitmap is stored in bitmap. Returns false and resets bitmap if 888 SkBitmap write did not succeed. 889 890 @param bitmap storage for legacy SkBitmap 891 @param legacyBitmapMode to be deprecated 892 @return true if SkBitmap was created 893 */ 894 bool asLegacyBitmap(SkBitmap* bitmap, LegacyBitmapMode legacyBitmapMode = kRO_LegacyBitmapMode) const; 895 896 /** Returns true if SkImage is backed by an image-generator or other service that creates 897 and caches its pixels or texture on-demand. 898 899 @return true if SkImage is created as needed 900 */ 901 bool isLazyGenerated() const; 902 903 /** Creates SkImage in target SkColorSpace. 904 Returns nullptr if SkImage could not be created. 905 906 Returns original SkImage if it is in target SkColorSpace. 907 Otherwise, converts pixels from SkImage SkColorSpace to target SkColorSpace. 908 If SkImage colorSpace() returns nullptr, SkImage SkColorSpace is assumed to be sRGB. 909 910 SkTransferFunctionBehavior is to be deprecated. 911 912 Set premulBehavior to SkTransferFunctionBehavior::kRespect to convert SkImage 913 pixels to a linear space, before converting to destination SkColorType 914 and SkColorSpace. 915 916 Set premulBehavior to SkTransferFunctionBehavior::kIgnore to treat SkImage 917 pixels as linear, when converting to destination SkColorType 918 and SkColorSpace, ignoring pixel encoding. 919 920 @param target SkColorSpace describing color range of returned SkImage 921 @param premulBehavior one of: SkTransferFunctionBehavior::kRespect, 922 SkTransferFunctionBehavior::kIgnore 923 @return created SkImage in target SkColorSpace 924 */ 925 sk_sp<SkImage> makeColorSpace(sk_sp<SkColorSpace> target, 926 SkTransferFunctionBehavior premulBehavior) const; 927 928 private: 929 SkImage(int width, int height, uint32_t uniqueID); 930 friend class SkImage_Base; 931 932 const int fWidth; 933 const int fHeight; 934 const uint32_t fUniqueID; 935 936 typedef SkRefCnt INHERITED; 937 }; 938 939 #endif 940
