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