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