SkImage.h 55 KB

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