SkSurface.h 48 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940
  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 SkSurface_DEFINED
  8. #define SkSurface_DEFINED
  9. #include "include/core/SkImage.h"
  10. #include "include/core/SkRefCnt.h"
  11. #include "include/core/SkSurfaceProps.h"
  12. #include "include/gpu/GrTypes.h"
  13. #if defined(SK_BUILD_FOR_ANDROID) && __ANDROID_API__ >= 26
  14. #include <android/hardware_buffer.h>
  15. #endif
  16. class SkCanvas;
  17. class SkDeferredDisplayList;
  18. class SkPaint;
  19. class SkSurfaceCharacterization;
  20. class GrBackendRenderTarget;
  21. class GrBackendSemaphore;
  22. class GrBackendTexture;
  23. class GrContext;
  24. class GrRecordingContext;
  25. class GrRenderTarget;
  26. /** \class SkSurface
  27. SkSurface is responsible for managing the pixels that a canvas draws into. The pixels can be
  28. allocated either in CPU memory (a raster surface) or on the GPU (a GrRenderTarget surface).
  29. SkSurface takes care of allocating a SkCanvas that will draw into the surface. Call
  30. surface->getCanvas() to use that canvas (but don't delete it, it is owned by the surface).
  31. SkSurface always has non-zero dimensions. If there is a request for a new surface, and either
  32. of the requested dimensions are zero, then nullptr will be returned.
  33. */
  34. class SK_API SkSurface : public SkRefCnt {
  35. public:
  36. /** Allocates raster SkSurface. SkCanvas returned by SkSurface draws directly into pixels.
  37. SkSurface is returned if all parameters are valid.
  38. Valid parameters include:
  39. info dimensions are greater than zero;
  40. info contains SkColorType and SkAlphaType supported by raster surface;
  41. pixels is not nullptr;
  42. rowBytes is large enough to contain info width pixels of SkColorType.
  43. Pixel buffer size should be info height times computed rowBytes.
  44. Pixels are not initialized.
  45. To access pixels after drawing, call flush() or peekPixels().
  46. @param imageInfo width, height, SkColorType, SkAlphaType, SkColorSpace,
  47. of raster surface; width and height must be greater than zero
  48. @param pixels pointer to destination pixels buffer
  49. @param rowBytes interval from one SkSurface row to the next
  50. @param surfaceProps LCD striping orientation and setting for device independent fonts;
  51. may be nullptr
  52. @return SkSurface if all parameters are valid; otherwise, nullptr
  53. */
  54. static sk_sp<SkSurface> MakeRasterDirect(const SkImageInfo& imageInfo, void* pixels,
  55. size_t rowBytes,
  56. const SkSurfaceProps* surfaceProps = nullptr);
  57. /** Allocates raster SkSurface. SkCanvas returned by SkSurface draws directly into pixels.
  58. releaseProc is called with pixels and context when SkSurface is deleted.
  59. SkSurface is returned if all parameters are valid.
  60. Valid parameters include:
  61. info dimensions are greater than zero;
  62. info contains SkColorType and SkAlphaType supported by raster surface;
  63. pixels is not nullptr;
  64. rowBytes is large enough to contain info width pixels of SkColorType.
  65. Pixel buffer size should be info height times computed rowBytes.
  66. Pixels are not initialized.
  67. To access pixels after drawing, call flush() or peekPixels().
  68. @param imageInfo width, height, SkColorType, SkAlphaType, SkColorSpace,
  69. of raster surface; width and height must be greater than zero
  70. @param pixels pointer to destination pixels buffer
  71. @param rowBytes interval from one SkSurface row to the next
  72. @param releaseProc called when SkSurface is deleted; may be nullptr
  73. @param context passed to releaseProc; may be nullptr
  74. @param surfaceProps LCD striping orientation and setting for device independent fonts;
  75. may be nullptr
  76. @return SkSurface if all parameters are valid; otherwise, nullptr
  77. */
  78. static sk_sp<SkSurface> MakeRasterDirectReleaseProc(const SkImageInfo& imageInfo, void* pixels,
  79. size_t rowBytes,
  80. void (*releaseProc)(void* pixels, void* context),
  81. void* context, const SkSurfaceProps* surfaceProps = nullptr);
  82. /** Allocates raster SkSurface. SkCanvas returned by SkSurface draws directly into pixels.
  83. Allocates and zeroes pixel memory. Pixel memory size is imageInfo.height() times
  84. rowBytes, or times imageInfo.minRowBytes() if rowBytes is zero.
  85. Pixel memory is deleted when SkSurface is deleted.
  86. SkSurface is returned if all parameters are valid.
  87. Valid parameters include:
  88. info dimensions are greater than zero;
  89. info contains SkColorType and SkAlphaType supported by raster surface;
  90. rowBytes is large enough to contain info width pixels of SkColorType, or is zero.
  91. If rowBytes is not zero, subsequent images returned by makeImageSnapshot()
  92. have the same rowBytes.
  93. @param imageInfo width, height, SkColorType, SkAlphaType, SkColorSpace,
  94. of raster surface; width and height must be greater than zero
  95. @param rowBytes interval from one SkSurface row to the next; may be zero
  96. @param surfaceProps LCD striping orientation and setting for device independent fonts;
  97. may be nullptr
  98. @return SkSurface if all parameters are valid; otherwise, nullptr
  99. */
  100. static sk_sp<SkSurface> MakeRaster(const SkImageInfo& imageInfo, size_t rowBytes,
  101. const SkSurfaceProps* surfaceProps);
  102. /** Allocates raster SkSurface. SkCanvas returned by SkSurface draws directly into pixels.
  103. Allocates and zeroes pixel memory. Pixel memory size is imageInfo.height() times
  104. imageInfo.minRowBytes().
  105. Pixel memory is deleted when SkSurface is deleted.
  106. SkSurface is returned if all parameters are valid.
  107. Valid parameters include:
  108. info dimensions are greater than zero;
  109. info contains SkColorType and SkAlphaType supported by raster surface.
  110. @param imageInfo width, height, SkColorType, SkAlphaType, SkColorSpace,
  111. of raster surface; width and height must be greater than zero
  112. @param props LCD striping orientation and setting for device independent fonts;
  113. may be nullptr
  114. @return SkSurface if all parameters are valid; otherwise, nullptr
  115. */
  116. static sk_sp<SkSurface> MakeRaster(const SkImageInfo& imageInfo,
  117. const SkSurfaceProps* props = nullptr) {
  118. return MakeRaster(imageInfo, 0, props);
  119. }
  120. /** Allocates raster SkSurface. SkCanvas returned by SkSurface draws directly into pixels.
  121. Allocates and zeroes pixel memory. Pixel memory size is height times width times
  122. four. Pixel memory is deleted when SkSurface is deleted.
  123. Internally, sets SkImageInfo to width, height, native color type, and
  124. kPremul_SkAlphaType.
  125. SkSurface is returned if width and height are greater than zero.
  126. Use to create SkSurface that matches SkPMColor, the native pixel arrangement on
  127. the platform. SkSurface drawn to output device skips converting its pixel format.
  128. @param width pixel column count; must be greater than zero
  129. @param height pixel row count; must be greater than zero
  130. @param surfaceProps LCD striping orientation and setting for device independent
  131. fonts; may be nullptr
  132. @return SkSurface if all parameters are valid; otherwise, nullptr
  133. */
  134. static sk_sp<SkSurface> MakeRasterN32Premul(int width, int height,
  135. const SkSurfaceProps* surfaceProps = nullptr);
  136. /** Caller data passed to RenderTarget/TextureReleaseProc; may be nullptr. */
  137. typedef void* ReleaseContext;
  138. /** User function called when supplied render target may be deleted. */
  139. typedef void (*RenderTargetReleaseProc)(ReleaseContext releaseContext);
  140. /** User function called when supplied texture may be deleted. */
  141. typedef void (*TextureReleaseProc)(ReleaseContext releaseContext);
  142. /** Wraps a GPU-backed texture into SkSurface. Caller must ensure the texture is
  143. valid for the lifetime of returned SkSurface. If sampleCnt greater than zero,
  144. creates an intermediate MSAA SkSurface which is used for drawing backendTexture.
  145. SkSurface is returned if all parameters are valid. backendTexture is valid if
  146. its pixel configuration agrees with colorSpace and context; for instance, if
  147. backendTexture has an sRGB configuration, then context must support sRGB,
  148. and colorSpace must be present. Further, backendTexture width and height must
  149. not exceed context capabilities, and the context must be able to support
  150. back-end textures.
  151. If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
  152. @param context GPU context
  153. @param backendTexture texture residing on GPU
  154. @param origin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
  155. @param sampleCnt samples per pixel, or 0 to disable full scene anti-aliasing
  156. @param colorType one of:
  157. kUnknown_SkColorType, kAlpha_8_SkColorType, kRGB_565_SkColorType,
  158. kARGB_4444_SkColorType, kRGBA_8888_SkColorType,
  159. kRGB_888x_SkColorType, kBGRA_8888_SkColorType,
  160. kRGBA_1010102_SkColorType, kRGB_101010x_SkColorType,
  161. kGray_8_SkColorType, kRGBA_F16_SkColorType
  162. @param colorSpace range of colors; may be nullptr
  163. @param surfaceProps LCD striping orientation and setting for device independent
  164. fonts; may be nullptr
  165. @param textureReleaseProc function called when texture can be released
  166. @param releaseContext state passed to textureReleaseProc
  167. @return SkSurface if all parameters are valid; otherwise, nullptr
  168. */
  169. static sk_sp<SkSurface> MakeFromBackendTexture(GrContext* context,
  170. const GrBackendTexture& backendTexture,
  171. GrSurfaceOrigin origin, int sampleCnt,
  172. SkColorType colorType,
  173. sk_sp<SkColorSpace> colorSpace,
  174. const SkSurfaceProps* surfaceProps,
  175. TextureReleaseProc textureReleaseProc = nullptr,
  176. ReleaseContext releaseContext = nullptr);
  177. /** Wraps a GPU-backed buffer into SkSurface. Caller must ensure backendRenderTarget
  178. is valid for the lifetime of returned SkSurface.
  179. SkSurface is returned if all parameters are valid. backendRenderTarget is valid if
  180. its pixel configuration agrees with colorSpace and context; for instance, if
  181. backendRenderTarget has an sRGB configuration, then context must support sRGB,
  182. and colorSpace must be present. Further, backendRenderTarget width and height must
  183. not exceed context capabilities, and the context must be able to support
  184. back-end render targets.
  185. If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
  186. @param context GPU context
  187. @param backendRenderTarget GPU intermediate memory buffer
  188. @param origin one of:
  189. kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
  190. @param colorType one of:
  191. kUnknown_SkColorType, kAlpha_8_SkColorType,
  192. kRGB_565_SkColorType,
  193. kARGB_4444_SkColorType, kRGBA_8888_SkColorType,
  194. kRGB_888x_SkColorType, kBGRA_8888_SkColorType,
  195. kRGBA_1010102_SkColorType, kRGB_101010x_SkColorType,
  196. kGray_8_SkColorType, kRGBA_F16_SkColorType
  197. @param colorSpace range of colors
  198. @param surfaceProps LCD striping orientation and setting for device independent
  199. fonts; may be nullptr
  200. @param releaseProc function called when texture can be released
  201. @param releaseContext state passed to textureReleaseProc
  202. @return SkSurface if all parameters are valid; otherwise, nullptr
  203. */
  204. static sk_sp<SkSurface> MakeFromBackendRenderTarget(GrContext* context,
  205. const GrBackendRenderTarget& backendRenderTarget,
  206. GrSurfaceOrigin origin,
  207. SkColorType colorType,
  208. sk_sp<SkColorSpace> colorSpace,
  209. const SkSurfaceProps* surfaceProps,
  210. RenderTargetReleaseProc releaseProc = nullptr,
  211. ReleaseContext releaseContext = nullptr);
  212. /** Wraps a GPU-backed texture into SkSurface. Caller must ensure backendTexture is
  213. valid for the lifetime of returned SkSurface. If sampleCnt greater than zero,
  214. creates an intermediate MSAA SkSurface which is used for drawing backendTexture.
  215. SkSurface is returned if all parameters are valid. backendTexture is valid if
  216. its pixel configuration agrees with colorSpace and context; for instance, if
  217. backendTexture has an sRGB configuration, then context must support sRGB,
  218. and colorSpace must be present. Further, backendTexture width and height must
  219. not exceed context capabilities.
  220. Returned SkSurface is available only for drawing into, and cannot generate an
  221. SkImage.
  222. If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
  223. @param context GPU context
  224. @param backendTexture texture residing on GPU
  225. @param origin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
  226. @param sampleCnt samples per pixel, or 0 to disable full scene anti-aliasing
  227. @param colorType one of:
  228. kUnknown_SkColorType, kAlpha_8_SkColorType, kRGB_565_SkColorType,
  229. kARGB_4444_SkColorType, kRGBA_8888_SkColorType,
  230. kRGB_888x_SkColorType, kBGRA_8888_SkColorType,
  231. kRGBA_1010102_SkColorType, kRGB_101010x_SkColorType,
  232. kGray_8_SkColorType, kRGBA_F16_SkColorType
  233. @param colorSpace range of colors; may be nullptr
  234. @param surfaceProps LCD striping orientation and setting for device independent
  235. fonts; may be nullptr
  236. @return SkSurface if all parameters are valid; otherwise, nullptr
  237. */
  238. static sk_sp<SkSurface> MakeFromBackendTextureAsRenderTarget(GrContext* context,
  239. const GrBackendTexture& backendTexture,
  240. GrSurfaceOrigin origin,
  241. int sampleCnt,
  242. SkColorType colorType,
  243. sk_sp<SkColorSpace> colorSpace,
  244. const SkSurfaceProps* surfaceProps);
  245. #if defined(SK_BUILD_FOR_ANDROID) && __ANDROID_API__ >= 26
  246. /** Private.
  247. Creates SkSurface from Android hardware buffer.
  248. Returned SkSurface takes a reference on the buffer. The ref on the buffer will be released
  249. when the SkSurface is destroyed and there is no pending work on the GPU involving the
  250. buffer.
  251. Only available on Android, when __ANDROID_API__ is defined to be 26 or greater.
  252. Currently this is only supported for buffers that can be textured as well as rendered to.
  253. In other workds that must have both AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT and
  254. AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE usage bits.
  255. @param context GPU context
  256. @param hardwareBuffer AHardwareBuffer Android hardware buffer
  257. @param origin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
  258. @param colorSpace range of colors; may be nullptr
  259. @param surfaceProps LCD striping orientation and setting for device independent
  260. fonts; may be nullptr
  261. @return created SkSurface, or nullptr
  262. */
  263. static sk_sp<SkSurface> MakeFromAHardwareBuffer(GrContext* context,
  264. AHardwareBuffer* hardwareBuffer,
  265. GrSurfaceOrigin origin,
  266. sk_sp<SkColorSpace> colorSpace,
  267. const SkSurfaceProps* surfaceProps);
  268. #endif
  269. /** Returns SkSurface on GPU indicated by context. Allocates memory for
  270. pixels, based on the width, height, and SkColorType in SkImageInfo. budgeted
  271. selects whether allocation for pixels is tracked by context. imageInfo
  272. describes the pixel format in SkColorType, and transparency in
  273. SkAlphaType, and color matching in SkColorSpace.
  274. sampleCount requests the number of samples per pixel.
  275. Pass zero to disable multi-sample anti-aliasing. The request is rounded
  276. up to the next supported count, or rounded down if it is larger than the
  277. maximum supported count.
  278. surfaceOrigin pins either the top-left or the bottom-left corner to the origin.
  279. shouldCreateWithMips hints that SkImage returned by makeImageSnapshot() is mip map.
  280. If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
  281. @param context GPU context
  282. @param budgeted one of: SkBudgeted::kNo, SkBudgeted::kYes
  283. @param imageInfo width, height, SkColorType, SkAlphaType, SkColorSpace;
  284. width, or height, or both, may be zero
  285. @param sampleCount samples per pixel, or 0 to disable full scene anti-aliasing
  286. @param surfaceOrigin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
  287. @param surfaceProps LCD striping orientation and setting for device independent
  288. fonts; may be nullptr
  289. @param shouldCreateWithMips hint that SkSurface will host mip map images
  290. @return SkSurface if all parameters are valid; otherwise, nullptr
  291. */
  292. static sk_sp<SkSurface> MakeRenderTarget(GrContext* context, SkBudgeted budgeted,
  293. const SkImageInfo& imageInfo,
  294. int sampleCount, GrSurfaceOrigin surfaceOrigin,
  295. const SkSurfaceProps* surfaceProps,
  296. bool shouldCreateWithMips = false);
  297. /** Returns SkSurface on GPU indicated by context. Allocates memory for
  298. pixels, based on the width, height, and SkColorType in SkImageInfo. budgeted
  299. selects whether allocation for pixels is tracked by context. imageInfo
  300. describes the pixel format in SkColorType, and transparency in
  301. SkAlphaType, and color matching in SkColorSpace.
  302. sampleCount requests the number of samples per pixel.
  303. Pass zero to disable multi-sample anti-aliasing. The request is rounded
  304. up to the next supported count, or rounded down if it is larger than the
  305. maximum supported count.
  306. SkSurface bottom-left corner is pinned to the origin.
  307. @param context GPU context
  308. @param budgeted one of: SkBudgeted::kNo, SkBudgeted::kYes
  309. @param imageInfo width, height, SkColorType, SkAlphaType, SkColorSpace,
  310. of raster surface; width, or height, or both, may be zero
  311. @param sampleCount samples per pixel, or 0 to disable multi-sample anti-aliasing
  312. @param surfaceProps LCD striping orientation and setting for device independent
  313. fonts; may be nullptr
  314. @return SkSurface if all parameters are valid; otherwise, nullptr
  315. */
  316. static sk_sp<SkSurface> MakeRenderTarget(GrContext* context, SkBudgeted budgeted,
  317. const SkImageInfo& imageInfo, int sampleCount,
  318. const SkSurfaceProps* surfaceProps) {
  319. return MakeRenderTarget(context, budgeted, imageInfo, sampleCount,
  320. kBottomLeft_GrSurfaceOrigin, surfaceProps);
  321. }
  322. /** Returns SkSurface on GPU indicated by context. Allocates memory for
  323. pixels, based on the width, height, and SkColorType in SkImageInfo. budgeted
  324. selects whether allocation for pixels is tracked by context. imageInfo
  325. describes the pixel format in SkColorType, and transparency in
  326. SkAlphaType, and color matching in SkColorSpace.
  327. SkSurface bottom-left corner is pinned to the origin.
  328. @param context GPU context
  329. @param budgeted one of: SkBudgeted::kNo, SkBudgeted::kYes
  330. @param imageInfo width, height, SkColorType, SkAlphaType, SkColorSpace,
  331. of raster surface; width, or height, or both, may be zero
  332. @return SkSurface if all parameters are valid; otherwise, nullptr
  333. */
  334. static sk_sp<SkSurface> MakeRenderTarget(GrContext* context, SkBudgeted budgeted,
  335. const SkImageInfo& imageInfo) {
  336. if (!imageInfo.width() || !imageInfo.height()) {
  337. return nullptr;
  338. }
  339. return MakeRenderTarget(context, budgeted, imageInfo, 0, kBottomLeft_GrSurfaceOrigin,
  340. nullptr);
  341. }
  342. /** Returns SkSurface on GPU indicated by context that is compatible with the provided
  343. characterization. budgeted selects whether allocation for pixels is tracked by context.
  344. @param context GPU context
  345. @param characterization description of the desired SkSurface
  346. @param budgeted one of: SkBudgeted::kNo, SkBudgeted::kYes
  347. @return SkSurface if all parameters are valid; otherwise, nullptr
  348. */
  349. static sk_sp<SkSurface> MakeRenderTarget(GrRecordingContext* context,
  350. const SkSurfaceCharacterization& characterization,
  351. SkBudgeted budgeted);
  352. /** Wraps a backend texture in an SkSurface - setting up the surface to match the provided
  353. characterization. The caller must ensure the texture is valid for the lifetime of
  354. returned SkSurface.
  355. If the backend texture and surface characterization are incompatible then null will
  356. be returned.
  357. Usually, the GrContext::createBackendTexture variant that takes a surface characterization
  358. should be used to create the backend texture. If not,
  359. SkSurfaceCharacterization::isCompatible can be used to determine if a given backend texture
  360. is compatible with a specific surface characterization.
  361. @param context GPU context
  362. @param characterization characterization of the desired surface
  363. @param backendTexture texture residing on GPU
  364. @param textureReleaseProc function called when texture can be released
  365. @param releaseContext state passed to textureReleaseProc
  366. @return SkSurface if all parameters are compatible; otherwise, nullptr
  367. */
  368. static sk_sp<SkSurface> MakeFromBackendTexture(GrContext* context,
  369. const SkSurfaceCharacterization& characterzation,
  370. const GrBackendTexture& backendTexture,
  371. TextureReleaseProc textureReleaseProc = nullptr,
  372. ReleaseContext releaseContext = nullptr);
  373. /** Is this surface compatible with the provided characterization?
  374. This method can be used to determine if an existing SkSurface is a viable destination
  375. for an SkDeferredDisplayList.
  376. @param characterization The characterization for which a compatibility check is desired
  377. @return true if this surface is compatible with the characterization;
  378. false otherwise
  379. */
  380. bool isCompatible(const SkSurfaceCharacterization& characterization) const;
  381. /** Returns SkSurface without backing pixels. Drawing to SkCanvas returned from SkSurface
  382. has no effect. Calling makeImageSnapshot() on returned SkSurface returns nullptr.
  383. @param width one or greater
  384. @param height one or greater
  385. @return SkSurface if width and height are positive; otherwise, nullptr
  386. */
  387. static sk_sp<SkSurface> MakeNull(int width, int height);
  388. /** Returns pixel count in each row; may be zero or greater.
  389. @return number of pixel columns
  390. */
  391. int width() const { return fWidth; }
  392. /** Returns pixel row count; may be zero or greater.
  393. @return number of pixel rows
  394. */
  395. int height() const { return fHeight; }
  396. /** Returns an ImageInfo describing the surface.
  397. */
  398. SkImageInfo imageInfo();
  399. /** Returns unique value identifying the content of SkSurface. Returned value changes
  400. each time the content changes. Content is changed by drawing, or by calling
  401. notifyContentWillChange().
  402. @return unique content identifier
  403. */
  404. uint32_t generationID();
  405. /** \enum SkSurface::ContentChangeMode
  406. ContentChangeMode members are parameters to notifyContentWillChange().
  407. */
  408. enum ContentChangeMode {
  409. kDiscard_ContentChangeMode, //!< discards surface on change
  410. kRetain_ContentChangeMode, //!< preserves surface on change
  411. };
  412. /** Notifies that SkSurface contents will be changed by code outside of Skia.
  413. Subsequent calls to generationID() return a different value.
  414. TODO: Can kRetain_ContentChangeMode be deprecated?
  415. @param mode one of: kDiscard_ContentChangeMode, kRetain_ContentChangeMode
  416. */
  417. void notifyContentWillChange(ContentChangeMode mode);
  418. enum BackendHandleAccess {
  419. kFlushRead_BackendHandleAccess, //!< back-end object is readable
  420. kFlushWrite_BackendHandleAccess, //!< back-end object is writable
  421. kDiscardWrite_BackendHandleAccess, //!< back-end object must be overwritten
  422. };
  423. /** Deprecated.
  424. */
  425. static const BackendHandleAccess kFlushRead_TextureHandleAccess =
  426. kFlushRead_BackendHandleAccess;
  427. /** Deprecated.
  428. */
  429. static const BackendHandleAccess kFlushWrite_TextureHandleAccess =
  430. kFlushWrite_BackendHandleAccess;
  431. /** Deprecated.
  432. */
  433. static const BackendHandleAccess kDiscardWrite_TextureHandleAccess =
  434. kDiscardWrite_BackendHandleAccess;
  435. /** Retrieves the back-end texture. If SkSurface has no back-end texture, an invalid
  436. object is returned. Call GrBackendTexture::isValid to determine if the result
  437. is valid.
  438. The returned GrBackendTexture should be discarded if the SkSurface is drawn to or deleted.
  439. @param backendHandleAccess one of: kFlushRead_BackendHandleAccess,
  440. kFlushWrite_BackendHandleAccess,
  441. kDiscardWrite_BackendHandleAccess
  442. @return GPU texture reference; invalid on failure
  443. */
  444. GrBackendTexture getBackendTexture(BackendHandleAccess backendHandleAccess);
  445. /** Retrieves the back-end render target. If SkSurface has no back-end render target, an invalid
  446. object is returned. Call GrBackendRenderTarget::isValid to determine if the result
  447. is valid.
  448. The returned GrBackendRenderTarget should be discarded if the SkSurface is drawn to
  449. or deleted.
  450. @param backendHandleAccess one of: kFlushRead_BackendHandleAccess,
  451. kFlushWrite_BackendHandleAccess,
  452. kDiscardWrite_BackendHandleAccess
  453. @return GPU render target reference; invalid on failure
  454. */
  455. GrBackendRenderTarget getBackendRenderTarget(BackendHandleAccess backendHandleAccess);
  456. /** If the surface was made via MakeFromBackendTexture then it's backing texture may be
  457. substituted with a different texture. The contents of the previous backing texture are
  458. copied into the new texture. SkCanvas state is preserved. The original sample count is
  459. used. The GrBackendFormat and dimensions of replacement texture must match that of
  460. the original.
  461. @param backendTexture the new backing texture for the surface.
  462. @param origin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
  463. @param textureReleaseProc function called when texture can be released
  464. @param releaseContext state passed to textureReleaseProc
  465. */
  466. bool replaceBackendTexture(const GrBackendTexture& backendTexture,
  467. GrSurfaceOrigin origin,
  468. TextureReleaseProc textureReleaseProc = nullptr,
  469. ReleaseContext releaseContext = nullptr);
  470. /** Returns SkCanvas that draws into SkSurface. Subsequent calls return the same SkCanvas.
  471. SkCanvas returned is managed and owned by SkSurface, and is deleted when SkSurface
  472. is deleted.
  473. @return drawing SkCanvas for SkSurface
  474. */
  475. SkCanvas* getCanvas();
  476. /** Returns a compatible SkSurface, or nullptr. Returned SkSurface contains
  477. the same raster, GPU, or null properties as the original. Returned SkSurface
  478. does not share the same pixels.
  479. Returns nullptr if imageInfo width or height are zero, or if imageInfo
  480. is incompatible with SkSurface.
  481. @param imageInfo width, height, SkColorType, SkAlphaType, SkColorSpace,
  482. of SkSurface; width and height must be greater than zero
  483. @return compatible SkSurface or nullptr
  484. */
  485. sk_sp<SkSurface> makeSurface(const SkImageInfo& imageInfo);
  486. /** Calls makeSurface(ImageInfo) with the same ImageInfo as this surface, but with the
  487. * specified width and height.
  488. */
  489. sk_sp<SkSurface> makeSurface(int width, int height);
  490. /** Returns SkImage capturing SkSurface contents. Subsequent drawing to SkSurface contents
  491. are not captured. SkImage allocation is accounted for if SkSurface was created with
  492. SkBudgeted::kYes.
  493. @return SkImage initialized with SkSurface contents
  494. */
  495. sk_sp<SkImage> makeImageSnapshot();
  496. /**
  497. * Like the no-parameter version, this returns an image of the current surface contents.
  498. * This variant takes a rectangle specifying the subset of the surface that is of interest.
  499. * These bounds will be sanitized before being used.
  500. * - If bounds extends beyond the surface, it will be trimmed to just the intersection of
  501. * it and the surface.
  502. * - If bounds does not intersect the surface, then this returns nullptr.
  503. * - If bounds == the surface, then this is the same as calling the no-parameter variant.
  504. */
  505. sk_sp<SkImage> makeImageSnapshot(const SkIRect& bounds);
  506. /** Draws SkSurface contents to canvas, with its top-left corner at (x, y).
  507. If SkPaint paint is not nullptr, apply SkColorFilter, alpha, SkImageFilter,
  508. SkBlendMode, and SkDrawLooper.
  509. @param canvas SkCanvas drawn into
  510. @param x horizontal offset in SkCanvas
  511. @param y vertical offset in SkCanvas
  512. @param paint SkPaint containing SkBlendMode, SkColorFilter, SkImageFilter,
  513. and so on; or nullptr
  514. */
  515. void draw(SkCanvas* canvas, SkScalar x, SkScalar y, const SkPaint* paint);
  516. /** Copies SkSurface pixel address, row bytes, and SkImageInfo to SkPixmap, if address
  517. is available, and returns true. If pixel address is not available, return
  518. false and leave SkPixmap unchanged.
  519. pixmap contents become invalid on any future change to SkSurface.
  520. @param pixmap storage for pixel state if pixels are readable; otherwise, ignored
  521. @return true if SkSurface has direct access to pixels
  522. */
  523. bool peekPixels(SkPixmap* pixmap);
  524. /** Copies SkRect of pixels to dst.
  525. Source SkRect corners are (srcX, srcY) and SkSurface (width(), height()).
  526. Destination SkRect corners are (0, 0) and (dst.width(), dst.height()).
  527. Copies each readable pixel intersecting both rectangles, without scaling,
  528. converting to dst.colorType() and dst.alphaType() if required.
  529. Pixels are readable when SkSurface is raster, or backed by a GPU.
  530. The destination pixel storage must be allocated by the caller.
  531. Pixel values are converted only if SkColorType and SkAlphaType
  532. do not match. Only pixels within both source and destination rectangles
  533. are copied. dst contents outside SkRect intersection are unchanged.
  534. Pass negative values for srcX or srcY to offset pixels across or down destination.
  535. Does not copy, and returns false if:
  536. - Source and destination rectangles do not intersect.
  537. - SkPixmap pixels could not be allocated.
  538. - dst.rowBytes() is too small to contain one row of pixels.
  539. @param dst storage for pixels copied from SkSurface
  540. @param srcX offset into readable pixels on x-axis; may be negative
  541. @param srcY offset into readable pixels on y-axis; may be negative
  542. @return true if pixels were copied
  543. */
  544. bool readPixels(const SkPixmap& dst, int srcX, int srcY);
  545. /** Copies SkRect of pixels from SkCanvas into dstPixels.
  546. Source SkRect corners are (srcX, srcY) and SkSurface (width(), height()).
  547. Destination SkRect corners are (0, 0) and (dstInfo.width(), dstInfo.height()).
  548. Copies each readable pixel intersecting both rectangles, without scaling,
  549. converting to dstInfo.colorType() and dstInfo.alphaType() if required.
  550. Pixels are readable when SkSurface is raster, or backed by a GPU.
  551. The destination pixel storage must be allocated by the caller.
  552. Pixel values are converted only if SkColorType and SkAlphaType
  553. do not match. Only pixels within both source and destination rectangles
  554. are copied. dstPixels contents outside SkRect intersection are unchanged.
  555. Pass negative values for srcX or srcY to offset pixels across or down destination.
  556. Does not copy, and returns false if:
  557. - Source and destination rectangles do not intersect.
  558. - SkSurface pixels could not be converted to dstInfo.colorType() or dstInfo.alphaType().
  559. - dstRowBytes is too small to contain one row of pixels.
  560. @param dstInfo width, height, SkColorType, and SkAlphaType of dstPixels
  561. @param dstPixels storage for pixels; dstInfo.height() times dstRowBytes, or larger
  562. @param dstRowBytes size of one destination row; dstInfo.width() times pixel size, or larger
  563. @param srcX offset into readable pixels on x-axis; may be negative
  564. @param srcY offset into readable pixels on y-axis; may be negative
  565. @return true if pixels were copied
  566. */
  567. bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes,
  568. int srcX, int srcY);
  569. /** Copies SkRect of pixels from SkSurface into bitmap.
  570. Source SkRect corners are (srcX, srcY) and SkSurface (width(), height()).
  571. Destination SkRect corners are (0, 0) and (bitmap.width(), bitmap.height()).
  572. Copies each readable pixel intersecting both rectangles, without scaling,
  573. converting to bitmap.colorType() and bitmap.alphaType() if required.
  574. Pixels are readable when SkSurface is raster, or backed by a GPU.
  575. The destination pixel storage must be allocated by the caller.
  576. Pixel values are converted only if SkColorType and SkAlphaType
  577. do not match. Only pixels within both source and destination rectangles
  578. are copied. dst contents outside SkRect intersection are unchanged.
  579. Pass negative values for srcX or srcY to offset pixels across or down destination.
  580. Does not copy, and returns false if:
  581. - Source and destination rectangles do not intersect.
  582. - SkSurface pixels could not be converted to dst.colorType() or dst.alphaType().
  583. - dst pixels could not be allocated.
  584. - dst.rowBytes() is too small to contain one row of pixels.
  585. @param dst storage for pixels copied from SkSurface
  586. @param srcX offset into readable pixels on x-axis; may be negative
  587. @param srcY offset into readable pixels on y-axis; may be negative
  588. @return true if pixels were copied
  589. */
  590. bool readPixels(const SkBitmap& dst, int srcX, int srcY);
  591. /** Makes pixel data available to caller, possibly asynchronously. Can perform rescaling.
  592. Currently asynchronous reads are only supported on the GPU backend and only when the
  593. underlying 3D API supports transfer buffers and CPU/GPU synchronization primitives. In all
  594. other cases this operates synchronously.
  595. Data is read from the source rectangle, is optionally converted to a linear gamma, is
  596. rescaled to the size indicated by 'info', is then converted to the color space, color type,
  597. and alpha type of 'info'.
  598. When the pixel data is ready the caller's ReadPixelsCallback is called with a pointer to
  599. the data in the requested color type, alpha type, and color space. The data pointer is
  600. only valid for the duration of the callback.
  601. Upon failure the the callback is called with nullptr as the data pointer.
  602. If the src rectangle is not contained by the bounds of the surface then failure occurs.
  603. Failure is indicated by calling callback with a nullptr for 'data'.
  604. @param info info of the requested pixels
  605. @param srcRect subrectangle of surface to read
  606. @param rescaleGamma controls whether rescaling is done in the surface's gamma or whether
  607. the source data is transformed to a linear gamma before rescaling.
  608. @param rescaleQuality controls the quality (and cost) of the rescaling
  609. @param callback function to call with result of the read
  610. @param context passed to callback
  611. */
  612. using ReadPixelsContext = void*;
  613. using ReadPixelsCallback = void(ReadPixelsContext, const void* data, size_t rowBytes);
  614. enum RescaleGamma : bool { kSrc, kLinear };
  615. void asyncRescaleAndReadPixels(const SkImageInfo& info, const SkIRect& srcRect,
  616. RescaleGamma rescaleGamma, SkFilterQuality rescaleQuality,
  617. ReadPixelsCallback callback, ReadPixelsContext context);
  618. /**
  619. Similar to asyncRescaleAndReadPixels but performs an additional conversion to YUV. The
  620. RGB->YUV conversion is controlled by 'yuvColorSpace'. The YUV data is returned as three
  621. planes ordered y, u, v. The u and v planes are half the width and height of the resized
  622. rectangle. Currently this fails if dstW or dstH are not even.
  623. On failure the callback is called with a null data pointer array. Fails if srcRect is not
  624. contained in the surface bounds.
  625. @param yuvColorSpace The transformation from RGB to YUV. Applied to the resized image
  626. after it is converted to dstColorSpace.
  627. @param dstColorSpace The color space to convert the resized image to, after rescaling.
  628. @param srcRect The portion of the surface to rescale and convert to YUV planes.
  629. @param dstW The width to rescale srcRect to
  630. @param dstH The height to rescale srcRect to
  631. @param rescaleGamma controls whether rescaling is done in the surface's gamma or whether
  632. the source data is transformed to a linear gamma before rescaling.
  633. @param rescaleQuality controls the quality (and cost) of the rescaling
  634. @param callback function to call with the planar read result
  635. @param context passed to callback
  636. */
  637. using ReadPixelsCallbackYUV420 = void(ReadPixelsContext, const void* data[3],
  638. size_t rowBytes[3]);
  639. void asyncRescaleAndReadPixelsYUV420(SkYUVColorSpace yuvColorSpace,
  640. sk_sp<SkColorSpace> dstColorSpace, const SkIRect& srcRect,
  641. int dstW, int dstH, RescaleGamma rescaleGamma,
  642. SkFilterQuality rescaleQuality,
  643. ReadPixelsCallbackYUV420 callback, ReadPixelsContext);
  644. /** Copies SkRect of pixels from the src SkPixmap to the SkSurface.
  645. Source SkRect corners are (0, 0) and (src.width(), src.height()).
  646. Destination SkRect corners are (dstX, dstY) and
  647. (dstX + Surface width(), dstY + Surface height()).
  648. Copies each readable pixel intersecting both rectangles, without scaling,
  649. converting to SkSurface colorType() and SkSurface alphaType() if required.
  650. @param src storage for pixels to copy to SkSurface
  651. @param dstX x-axis position relative to SkSurface to begin copy; may be negative
  652. @param dstY y-axis position relative to SkSurface to begin copy; may be negative
  653. */
  654. void writePixels(const SkPixmap& src, int dstX, int dstY);
  655. /** Copies SkRect of pixels from the src SkBitmap to the SkSurface.
  656. Source SkRect corners are (0, 0) and (src.width(), src.height()).
  657. Destination SkRect corners are (dstX, dstY) and
  658. (dstX + Surface width(), dstY + Surface height()).
  659. Copies each readable pixel intersecting both rectangles, without scaling,
  660. converting to SkSurface colorType() and SkSurface alphaType() if required.
  661. @param src storage for pixels to copy to SkSurface
  662. @param dstX x-axis position relative to SkSurface to begin copy; may be negative
  663. @param dstY y-axis position relative to SkSurface to begin copy; may be negative
  664. */
  665. void writePixels(const SkBitmap& src, int dstX, int dstY);
  666. /** Returns SkSurfaceProps for surface.
  667. @return LCD striping orientation and setting for device independent fonts
  668. */
  669. const SkSurfaceProps& props() const { return fProps; }
  670. /** Issues pending SkSurface commands to the GPU-backed API and resolves any SkSurface MSAA.
  671. Skia flushes as needed, so it is not necessary to call this if Skia manages
  672. drawing and object lifetime. Call when interleaving Skia calls with native
  673. GPU calls.
  674. */
  675. void flush();
  676. enum class BackendSurfaceAccess {
  677. kNoAccess, //!< back-end object will not be used by client
  678. kPresent, //!< back-end surface will be used for presenting to screen
  679. };
  680. /** Issues pending SkSurface commands to the GPU-backed API and resolves any SkSurface MSAA.
  681. The work that is submitted to the GPU will be dependent on the BackendSurfaceAccess that is
  682. passed in.
  683. If BackendSurfaceAccess::kNoAccess is passed in all commands will be issued to the GPU.
  684. If BackendSurfaceAccess::kPresent is passed in and the backend API is not Vulkan, it is
  685. treated the same as kNoAccess. If the backend API is Vulkan, the VkImage that backs the
  686. SkSurface will be transferred back to its original queue. If the SkSurface was created by
  687. wrapping a VkImage, the queue will be set to the queue which was originally passed in on
  688. the GrVkImageInfo. Additionally, if the original queue was not external or foreign the
  689. layout of the VkImage will be set to VK_IMAGE_LAYOUT_PRESENT_SRC_KHR.
  690. The GrFlushInfo describes additional options to flush. Please see documentation at
  691. GrFlushInfo for more info.
  692. If GrSemaphoresSubmitted::kNo is returned, the GPU back-end did not create or
  693. add any semaphores to signal on the GPU; the caller should not instruct the GPU
  694. to wait on any of the semaphores passed in the GrFlushInfo.
  695. Pending surface commands are flushed regardless of the return result.
  696. @param access type of access the call will do on the backend object after flush
  697. @param info flush options
  698. @return one of: GrSemaphoresSubmitted::kYes, GrSemaphoresSubmitted::kNo
  699. */
  700. GrSemaphoresSubmitted flush(BackendSurfaceAccess access, const GrFlushInfo& info);
  701. /** Deprecated
  702. */
  703. GrSemaphoresSubmitted flush(BackendSurfaceAccess access, GrFlushFlags flags,
  704. int numSemaphores, GrBackendSemaphore signalSemaphores[],
  705. GrGpuFinishedProc finishedProc = nullptr,
  706. GrGpuFinishedContext finishedContext = nullptr);
  707. /** The below enum and flush call are deprecated
  708. */
  709. enum FlushFlags {
  710. kNone_FlushFlags = 0,
  711. // flush will wait till all submitted GPU work is finished before returning.
  712. kSyncCpu_FlushFlag = 0x1,
  713. };
  714. GrSemaphoresSubmitted flush(BackendSurfaceAccess access, FlushFlags flags,
  715. int numSemaphores, GrBackendSemaphore signalSemaphores[]);
  716. /** Deprecated.
  717. */
  718. GrSemaphoresSubmitted flushAndSignalSemaphores(int numSemaphores,
  719. GrBackendSemaphore signalSemaphores[]);
  720. /** Inserts a list of GPU semaphores that the current GPU-backed API must wait on before
  721. executing any more commands on the GPU for this surface. Skia will take ownership of the
  722. underlying semaphores and delete them once they have been signaled and waited on.
  723. If this call returns false, then the GPU back-end will not wait on any passed in semaphores,
  724. and the client will still own the semaphores.
  725. @param numSemaphores size of waitSemaphores array
  726. @param waitSemaphores array of semaphore containers
  727. @return true if GPU is waiting on semaphores
  728. */
  729. bool wait(int numSemaphores, const GrBackendSemaphore* waitSemaphores);
  730. /** Initializes SkSurfaceCharacterization that can be used to perform GPU back-end
  731. processing in a separate thread. Typically this is used to divide drawing
  732. into multiple tiles. SkDeferredDisplayListRecorder records the drawing commands
  733. for each tile.
  734. Return true if SkSurface supports characterization. raster surface returns false.
  735. @param characterization properties for parallel drawing
  736. @return true if supported
  737. */
  738. bool characterize(SkSurfaceCharacterization* characterization) const;
  739. /** Draws deferred display list created using SkDeferredDisplayListRecorder.
  740. Has no effect and returns false if SkSurfaceCharacterization stored in
  741. deferredDisplayList is not compatible with SkSurface.
  742. raster surface returns false.
  743. @param deferredDisplayList drawing commands
  744. @return false if deferredDisplayList is not compatible
  745. */
  746. bool draw(SkDeferredDisplayList* deferredDisplayList);
  747. protected:
  748. SkSurface(int width, int height, const SkSurfaceProps* surfaceProps);
  749. SkSurface(const SkImageInfo& imageInfo, const SkSurfaceProps* surfaceProps);
  750. // called by subclass if their contents have changed
  751. void dirtyGenerationID() {
  752. fGenerationID = 0;
  753. }
  754. private:
  755. const SkSurfaceProps fProps;
  756. const int fWidth;
  757. const int fHeight;
  758. uint32_t fGenerationID;
  759. typedef SkRefCnt INHERITED;
  760. };
  761. #endif