blob: d692eb4c7373de682404e8f7cda7a02aa9cce840 [file] [log] [blame]
Cary Clarka560c472017-11-27 10:44:06 -05001#Topic Surface
2#Alias Surface_Reference
3
Cary Clark08895c42018-02-01 09:37:32 -05004#Subtopic Overview
Cary Clark4855f782018-02-06 09:41:53 -05005 #Subtopic Subtopic
Cary Clark08895c42018-02-01 09:37:32 -05006 #Populate
7 ##
8##
9
Cary Clarka560c472017-11-27 10:44:06 -050010#Class SkSurface
11
12SkSurface is responsible for managing the pixels that a canvas draws into. The pixels can be
13allocated either in CPU memory (a raster surface) or on the GPU (a GrRenderTarget surface).
14SkSurface takes care of allocating a SkCanvas that will draw into the surface. Call
15surface->getCanvas() to use that canvas (but don't delete it, it is owned by the surface).
16SkSurface always has non-zero dimensions. If there is a request for a new surface, and either
17of the requested dimensions are zero, then nullptr will be returned.
18
Cary Clark4855f782018-02-06 09:41:53 -050019#Subtopic Related_Function
Cary Clark08895c42018-02-01 09:37:32 -050020#Populate
Cary Clark4855f782018-02-06 09:41:53 -050021#Subtopic ##
Cary Clarka560c472017-11-27 10:44:06 -050022
Cary Clark4855f782018-02-06 09:41:53 -050023#Subtopic Member_Function
Cary Clark08895c42018-02-01 09:37:32 -050024#Populate
25##
Cary Clarka560c472017-11-27 10:44:06 -050026
27# ------------------------------------------------------------------------------
Cary Clark4855f782018-02-06 09:41:53 -050028#Subtopic Constructor
29#Populate
30##
Cary Clarka560c472017-11-27 10:44:06 -050031
32#Method static sk_sp<SkSurface> MakeRasterDirect(const SkImageInfo& imageInfo, void* pixels,
33 size_t rowBytes,
34 const SkSurfaceProps* surfaceProps = nullptr)
Cary Clark4855f782018-02-06 09:41:53 -050035#In Constructor
Cary Clarkab2621d2018-01-30 10:08:57 -050036#Line # creates Surface from SkImageInfo and Pixel_Storage ##
Cary Clarka560c472017-11-27 10:44:06 -050037
38Allocates raster Surface. Canvas returned by Surface draws directly into pixels.
39
40Surface is returned if all parameters are valid.
41Valid parameters include:
42info dimensions are greater than zero;
Cary Clark2dc84ad2018-01-26 12:56:22 -050043info contains Color_Type and Alpha_Type supported by Raster_Surface;
Cary Clarka560c472017-11-27 10:44:06 -050044pixels is not nullptr;
Cary Clark2dc84ad2018-01-26 12:56:22 -050045rowBytes is large enough to contain info width pixels of Color_Type.
Cary Clarka560c472017-11-27 10:44:06 -050046
47Pixel buffer size should be info height times computed rowBytes.
48Pixels are not initialized.
49To access pixels after drawing, call flush() or peekPixels.
50
Cary Clark2dc84ad2018-01-26 12:56:22 -050051#Param imageInfo width, height, Color_Type, Alpha_Type, Color_Space,
Cary Clarka560c472017-11-27 10:44:06 -050052 of Raster_Surface; width and height must be greater than zero
53##
54#Param pixels pointer to destination pixels buffer ##
55#Param rowBytes interval from one Surface row to the next ##
56#Param surfaceProps LCD striping orientation and setting for device independent fonts;
57 may be nullptr
58##
59
60#Return Surface if all parameters are valid; otherwise, nullptr ##
61
62#Example
63void draw(SkCanvas* ) {
64 SkImageInfo info = SkImageInfo::MakeN32Premul(3, 3);
65 const size_t size = info.computeMinByteSize();
66 SkAutoTMalloc<SkPMColor> storage(size);
67 SkPMColor* pixels = storage.get();
68 sk_sp<SkSurface> surface(SkSurface::MakeRasterDirect(info, pixels, info.minRowBytes()));
69 SkCanvas* canvas = surface->getCanvas();
70 canvas->clear(SK_ColorWHITE);
71 SkPMColor pmWhite = pixels[0];
72 SkPaint paint;
73 canvas->drawPoint(1, 1, paint);
74 canvas->flush(); // ensure that point was drawn
75 for (int y = 0; y < info.height(); ++y) {
76 for (int x = 0; x < info.width(); ++x) {
77 SkDebugf("%c", *pixels++ == pmWhite ? '-' : 'x');
78 }
79 SkDebugf("\n");
80 }
81}
82 #StdOut
83 ---
84 -x-
85 ---
86 ##
87##
88
89#SeeAlso MakeRasterDirectReleaseProc MakeRaster MakeRasterN32Premul SkCanvas::MakeRasterDirect
90
91#Method ##
92
93# ------------------------------------------------------------------------------
94
95#Method static sk_sp<SkSurface> MakeRasterDirectReleaseProc(const SkImageInfo& imageInfo, void* pixels,
96 size_t rowBytes,
97 void (*releaseProc)(void* pixels, void* context),
98 void* context, const SkSurfaceProps* surfaceProps = nullptr)
Cary Clark4855f782018-02-06 09:41:53 -050099#In Constructor
Cary Clarkab2621d2018-01-30 10:08:57 -0500100#Line # creates Surface from SkImageInfo and Pixel_Storage ##
Cary Clarka560c472017-11-27 10:44:06 -0500101
102Allocates raster Surface. Canvas returned by Surface draws directly into pixels.
103releaseProc is called with pixels and context when Surface is deleted.
104
105Surface is returned if all parameters are valid.
106Valid parameters include:
107info dimensions are greater than zero;
Cary Clark2dc84ad2018-01-26 12:56:22 -0500108info contains Color_Type and Alpha_Type supported by Raster_Surface;
Cary Clarka560c472017-11-27 10:44:06 -0500109pixels is not nullptr;
Cary Clark2dc84ad2018-01-26 12:56:22 -0500110rowBytes is large enough to contain info width pixels of Color_Type.
Cary Clarka560c472017-11-27 10:44:06 -0500111
112Pixel buffer size should be info height times computed rowBytes.
113Pixels are not initialized.
114To access pixels after drawing, call flush() or peekPixels.
115
Cary Clark2dc84ad2018-01-26 12:56:22 -0500116#Param imageInfo width, height, Color_Type, Alpha_Type, Color_Space,
Cary Clarka560c472017-11-27 10:44:06 -0500117 of Raster_Surface; width and height must be greater than zero
118##
119#Param pixels pointer to destination pixels buffer ##
120#Param rowBytes interval from one Surface row to the next ##
121#Param releaseProc called when Surface is deleted; may be nullptr ##
122#Param context passed to releaseProc; may be nullptr ##
123#Param surfaceProps LCD striping orientation and setting for device independent fonts;
124 may be nullptr
125##
126
127#Return Surface if all parameters are valid; otherwise, nullptr ##
128
129#Example
130#Function
131static void release_direct_surface_storage(void* pixels, void* context) {
132 if (pixels == context) {
133 SkDebugf("expected release context\n");
134 }
135 sk_free(pixels);
136}
137
138##
139void draw(SkCanvas* ) {
140 SkImageInfo info = SkImageInfo::MakeN32Premul(3, 3);
141 const size_t rowBytes = info.minRowBytes();
142 void* pixels = sk_malloc_throw(info.computeByteSize(rowBytes));
143 sk_sp<SkSurface> surface(SkSurface::MakeRasterDirectReleaseProc(info, pixels, rowBytes,
144 release_direct_surface_storage, pixels));
145 SkCanvas* canvas = surface->getCanvas();
146 canvas->clear(SK_ColorWHITE);
147 SkPMColor* colorPtr = (SkPMColor*) pixels;
148 SkPMColor pmWhite = colorPtr[0];
149 SkPaint paint;
150 canvas->drawPoint(1, 1, paint);
151 canvas->flush(); // ensure that point was drawn
152 for (int y = 0; y < info.height(); ++y) {
153 for (int x = 0; x < info.width(); ++x) {
154 SkDebugf("%c", *colorPtr++ == pmWhite ? '-' : 'x');
155 }
156 SkDebugf("\n");
157 }
158}
159#StdOut
160---
161-x-
162---
163expected release context
164##
165##
166
167#SeeAlso MakeRasterDirect MakeRasterN32Premul MakeRaster
168
169#Method ##
170
171# ------------------------------------------------------------------------------
172
173#Method static sk_sp<SkSurface> MakeRaster(const SkImageInfo& imageInfo, size_t rowBytes,
174 const SkSurfaceProps* surfaceProps)
Cary Clark4855f782018-02-06 09:41:53 -0500175#In Constructor
Cary Clarkab2621d2018-01-30 10:08:57 -0500176#Line # creates Surface from SkImageInfo ##
Cary Clarka560c472017-11-27 10:44:06 -0500177
178Allocates raster Surface. Canvas returned by Surface draws directly into pixels.
179Allocates and zeroes pixel memory. Pixel memory size is imageInfo.height() times
180rowBytes, or times imageInfo.minRowBytes() if rowBytes is zero.
181Pixel memory is deleted when Surface is deleted.
182
183Surface is returned if all parameters are valid.
184Valid parameters include:
185info dimensions are greater than zero;
Cary Clark2dc84ad2018-01-26 12:56:22 -0500186info contains Color_Type and Alpha_Type supported by Raster_Surface;
187rowBytes is large enough to contain info width pixels of Color_Type, or is zero.
Cary Clarka560c472017-11-27 10:44:06 -0500188
189If rowBytes is not zero, subsequent images returned by makeImageSnapshot
190have the same rowBytes.
191
Cary Clark2dc84ad2018-01-26 12:56:22 -0500192#Param imageInfo width, height, Color_Type, Alpha_Type, Color_Space,
Cary Clarka560c472017-11-27 10:44:06 -0500193 of Raster_Surface; width and height must be greater than zero
194##
195#Param rowBytes interval from one Surface row to the next; may be zero ##
196#Param surfaceProps LCD striping orientation and setting for device independent fonts;
197 may be nullptr
198##
199
200#Return Surface if all parameters are valid; otherwise, nullptr ##
201
202#Example
203void draw(SkCanvas* ) {
204 SkImageInfo info = SkImageInfo::MakeN32Premul(3, 3);
205 const size_t rowBytes = 64;
206 sk_sp<SkSurface> surface(SkSurface::MakeRaster(info, rowBytes, nullptr));
207 SkCanvas* canvas = surface->getCanvas();
208 canvas->clear(SK_ColorWHITE);
209 SkPixmap pixmap;
210 if (surface->peekPixels(&pixmap)) {
211 const uint32_t* colorPtr = pixmap.addr32();
212 SkPMColor pmWhite = colorPtr[0];
213 SkPaint paint;
214 canvas->drawPoint(1, 1, paint);
215 canvas->flush(); // ensure that point was drawn
216 for (int y = 0; y < info.height(); ++y) {
217 for (int x = 0; x < info.width(); ++x) {
218 SkDebugf("%c", colorPtr[x] == pmWhite ? '-' : 'x');
219 }
220 colorPtr += rowBytes / sizeof(colorPtr[0]);
221 SkDebugf("\n");
222 }
223 }
224}
225#StdOut
226---
227-x-
228---
229##
230##
231
232#SeeAlso MakeRasterDirect MakeRasterN32Premul MakeRasterDirectReleaseProc
233
234#Method ##
235
236# ------------------------------------------------------------------------------
237
238#Method static sk_sp<SkSurface> MakeRaster(const SkImageInfo& imageInfo,
239 const SkSurfaceProps* props = nullptr)
240
241Allocates raster Surface. Canvas returned by Surface draws directly into pixels.
242Allocates and zeroes pixel memory. Pixel memory size is imageInfo.height() times
243imageInfo.minRowBytes().
244Pixel memory is deleted when Surface is deleted.
245
246Surface is returned if all parameters are valid.
247Valid parameters include:
248info dimensions are greater than zero;
Cary Clark2dc84ad2018-01-26 12:56:22 -0500249info contains Color_Type and Alpha_Type supported by Raster_Surface.
Cary Clarka560c472017-11-27 10:44:06 -0500250
Cary Clark2dc84ad2018-01-26 12:56:22 -0500251#Param imageInfo width, height, Color_Type, Alpha_Type, Color_Space,
Cary Clarka560c472017-11-27 10:44:06 -0500252 of Raster_Surface; width and height must be greater than zero
253##
254#Param props LCD striping orientation and setting for device independent fonts;
255 may be nullptr
256##
257
258#Return Surface if all parameters are valid; otherwise, nullptr ##
259
260#Example
261void draw(SkCanvas* ) {
262 SkImageInfo info = SkImageInfo::MakeN32Premul(3, 3);
263 sk_sp<SkSurface> surface(SkSurface::MakeRaster(info));
264 SkCanvas* canvas = surface->getCanvas();
265 canvas->clear(SK_ColorWHITE);
266 SkPixmap pixmap;
267 if (surface->peekPixels(&pixmap)) {
268 const uint32_t* colorPtr = pixmap.addr32();
269 SkPMColor pmWhite = colorPtr[0];
270 SkPaint paint;
271 canvas->drawPoint(1, 1, paint);
272 canvas->flush(); // ensure that point was drawn
273 for (int y = 0; y < info.height(); ++y) {
274 for (int x = 0; x < info.width(); ++x) {
275 SkDebugf("%c", colorPtr[x] == pmWhite ? '-' : 'x');
276 }
277 colorPtr += info.width();
278 SkDebugf("\n");
279 }
280 }
281}
282##
283
284#SeeAlso MakeRasterDirect MakeRasterN32Premul MakeRasterDirectReleaseProc
285
286#Method ##
287
288# ------------------------------------------------------------------------------
289
290#Method static sk_sp<SkSurface> MakeRasterN32Premul(int width, int height,
291 const SkSurfaceProps* surfaceProps = nullptr)
Cary Clark4855f782018-02-06 09:41:53 -0500292#In Constructor
Cary Clarkab2621d2018-01-30 10:08:57 -0500293#Line # creates Surface from width, height matching output ##
Cary Clarka560c472017-11-27 10:44:06 -0500294
295Allocates raster Surface. Canvas returned by Surface draws directly into pixels.
296Allocates and zeroes pixel memory. Pixel memory size is height times width times
297four. Pixel memory is deleted when Surface is deleted.
298
299Internally, sets Image_Info to width, height, Native_Color_Type, and
300kPremul_SkAlphaType.
301
302Surface is returned if width and height are greater than zero.
303
304Use to create Surface that matches SkPMColor, the native pixel arrangement on
305the platform. Surface drawn to output device skips converting its pixel format.
306
307#Param width pixel column count; must be greater than zero ##
308#Param height pixel row count; must be greater than zero ##
309#Param surfaceProps LCD striping orientation and setting for device independent
310 fonts; may be nullptr
311##
312
313#Return Surface if all parameters are valid; otherwise, nullptr ##
314
315#Example
316void draw(SkCanvas* ) {
317 sk_sp<SkSurface> surface(SkSurface::MakeRasterN32Premul(3, 3));
318 SkCanvas* canvas = surface->getCanvas();
319 canvas->clear(SK_ColorWHITE);
320 SkPixmap pixmap;
321 if (surface->peekPixels(&pixmap)) {
322 const uint32_t* colorPtr = pixmap.addr32();
323 SkPMColor pmWhite = colorPtr[0];
324 SkPaint paint;
325 canvas->drawPoint(1, 1, paint);
326 canvas->flush(); // ensure that point was drawn
327 for (int y = 0; y < surface->height(); ++y) {
328 for (int x = 0; x < surface->width(); ++x) {
329 SkDebugf("%c", colorPtr[x] == pmWhite ? '-' : 'x');
330 }
331 colorPtr += surface->width();
332 SkDebugf("\n");
333 }
334 }
335}
336#StdOut
337---
338-x-
339---
340##
341##
342
343#SeeAlso MakeRasterDirect MakeRasterN32Premul MakeRasterDirectReleaseProc
344
345#Method ##
346
347# ------------------------------------------------------------------------------
348
349#Method static sk_sp<SkSurface> MakeFromBackendTexture(GrContext* context,
350 const GrBackendTexture& backendTexture,
351 GrSurfaceOrigin origin, int sampleCnt,
352 sk_sp<SkColorSpace> colorSpace,
353 const SkSurfaceProps* surfaceProps)
Cary Clark4855f782018-02-06 09:41:53 -0500354#In Constructor
Cary Clarkab2621d2018-01-30 10:08:57 -0500355#Line # creates Surface from GPU-backed texture ##
Cary Clarka560c472017-11-27 10:44:06 -0500356
357Wraps a GPU-backed texture into Surface. Caller must ensure the texture is
358valid for the lifetime of returned Surface. If sampleCnt greater than zero,
359creates an intermediate MSAA Surface which is used for drawing backendTexture.
360
361Surface is returned if all parameters are valid. backendTexture is valid if
362its pixel configuration agrees with colorSpace and context; for instance, if
363backendTexture has an sRGB configuration, then context must support sRGB,
364and colorSpace must be present. Further, backendTexture width and height must
365not exceed context capabilities, and the context must be able to support
366back-end textures.
367
368If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
369
370#Param context GPU_Context ##
371#Param backendTexture texture residing on GPU ##
372#Param origin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin ##
373#Param sampleCnt samples per pixel, or 0 to disable full scene anti-aliasing ##
374#Param colorSpace range of colors ##
375#Param surfaceProps LCD striping orientation and setting for device independent
376 fonts; may be nullptr
377##
378
379#Return Surface if all parameters are valid; otherwise, nullptr ##
380
381#Example
382#ToDo remove !fiddle below once backEndTextureRenderTarget is available ##
383#Platform !fiddle gpu cpu
384 SkPaint paint;
385 paint.setTextSize(32);
386 GrContext* context = canvas->getGrContext();
387 if (!context) {
388 canvas->drawString("GPU only!", 20, 40, paint);
389 return;
390 }
391 sk_sp<SkSurface> gpuSurface = SkSurface::MakeFromBackendTexture(context,
392 backEndTextureRenderTarget, kTopLeft_GrSurfaceOrigin, 0, nullptr, nullptr);
393 auto surfaceCanvas = gpuSurface->getCanvas();
394 surfaceCanvas->clear(SK_ColorWHITE);
395 surfaceCanvas->drawString("GPU rocks!", 20, 40, paint);
396 sk_sp<SkImage> image(gpuSurface->makeImageSnapshot());
397 canvas->drawImage(image, 0, 0);
398##
399
400#SeeAlso GrBackendTexture MakeFromBackendRenderTarget MakeRenderTarget
401
402#Method ##
403
404# ------------------------------------------------------------------------------
405
Cary Clarkf059e7c2017-12-20 14:53:21 -0500406#Method static sk_sp<SkSurface> MakeFromBackendTexture(GrContext* context,
407 const GrBackendTexture& backendTexture,
408 GrSurfaceOrigin origin, int sampleCnt,
409 SkColorType colorType,
410 sk_sp<SkColorSpace> colorSpace,
411 const SkSurfaceProps* surfaceProps)
412
413Wraps a GPU-backed texture into Surface. Caller must ensure the texture is
414valid for the lifetime of returned Surface. If sampleCnt greater than zero,
415creates an intermediate MSAA Surface which is used for drawing backendTexture.
416
417Surface is returned if all parameters are valid. backendTexture is valid if
418its pixel configuration agrees with colorSpace and context; for instance, if
419backendTexture has an sRGB configuration, then context must support sRGB,
420and colorSpace must be present. Further, backendTexture width and height must
421not exceed context capabilities, and the context must be able to support
422back-end textures.
423
424If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
425
426#Param context GPU_Context ##
427#Param backendTexture texture residing on GPU ##
428#Param origin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin ##
429#Param sampleCnt samples per pixel, or 0 to disable full scene anti-aliasing ##
430#Param colorType one of: kUnknown_SkColorType, kAlpha_8_SkColorType,
431 kRGB_565_SkColorType, kARGB_4444_SkColorType,
432 kRGBA_8888_SkColorType, kBGRA_8888_SkColorType,
433 kGray_8_SkColorType, kRGBA_F16_SkColorType
434##
435#Param colorSpace range of colors ##
436#Param surfaceProps LCD striping orientation and setting for device independent
437 fonts; may be nullptr
438##
439
440#Return Surface if all parameters are valid; otherwise, nullptr ##
441
442#Example
443#ToDo remove !fiddle below once backEndTextureRenderTarget is available ##
444#Platform !fiddle gpu cpu
445 SkPaint paint;
446 paint.setTextSize(32);
447 GrContext* context = canvas->getGrContext();
448 if (!context) {
449 canvas->drawString("GPU only!", 20, 40, paint);
450 return;
451 }
452 sk_sp<SkSurface> gpuSurface = SkSurface::MakeFromBackendTexture(context,
453 backEndTextureRenderTarget, kTopLeft_GrSurfaceOrigin,
454 kRGBA_8888_SkColorType, 0, nullptr, nullptr);
455 auto surfaceCanvas = gpuSurface->getCanvas();
456 surfaceCanvas->clear(SK_ColorWHITE);
457 surfaceCanvas->drawString("GPU rocks!", 20, 40, paint);
458 sk_sp<SkImage> image(gpuSurface->makeImageSnapshot());
459 canvas->drawImage(image, 0, 0);
460##
461
462#SeeAlso GrBackendTexture MakeFromBackendRenderTarget MakeRenderTarget
463
464#Method ##
465
466# ------------------------------------------------------------------------------
467
Cary Clarka560c472017-11-27 10:44:06 -0500468#Method static sk_sp<SkSurface> MakeFromBackendRenderTarget(GrContext* context,
469 const GrBackendRenderTarget& backendRenderTarget,
470 GrSurfaceOrigin origin,
471 sk_sp<SkColorSpace> colorSpace,
472 const SkSurfaceProps* surfaceProps)
Cary Clark4855f782018-02-06 09:41:53 -0500473#In Constructor
Cary Clarkab2621d2018-01-30 10:08:57 -0500474#Line # creates Surface from GPU memory buffer ##
Cary Clarka560c472017-11-27 10:44:06 -0500475
476Wraps a GPU-backed buffer into Surface. Caller must ensure render target is
477valid for the lifetime of returned Surface.
478
479Surface is returned if all parameters are valid. backendRenderTarget is valid if
480its pixel configuration agrees with colorSpace and context; for instance, if
481backendRenderTarget has an sRGB configuration, then context must support sRGB,
482and colorSpace must be present. Further, backendRenderTarget width and height must
483not exceed context capabilities, and the context must be able to support
484back-end render targets.
485
486If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
487
488#Param context GPU_Context ##
489#Param backendRenderTarget GPU intermediate memory buffer ##
490#Param origin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin ##
491#Param colorSpace range of colors ##
492#Param surfaceProps LCD striping orientation and setting for device independent
493 fonts; may be nullptr
494##
495
496#Return Surface if all parameters are valid; otherwise, nullptr ##
497
498#Example
499#ToDo remove !fiddle below once backEndTextureRenderTarget is available ##
500#Platform !fiddle gpu
501 SkPaint paint;
502 paint.setTextSize(32);
503 GrContext* context = canvas->getGrContext();
504 if (!context) {
505 canvas->drawString("GPU only!", 20, 40, paint);
506 return;
507 }
508 sk_sp<SkSurface> gpuSurface = SkSurface::MakeFromBackendRenderTarget(context,
509 backEndRenderTarget, kTopLeft_GrSurfaceOrigin, nullptr, nullptr);
510 auto surfaceCanvas = gpuSurface->getCanvas();
511 surfaceCanvas->clear(SK_ColorWHITE);
512 surfaceCanvas->drawString("GPU rocks!", 20, 40, paint);
513 sk_sp<SkImage> image(gpuSurface->makeImageSnapshot());
514 canvas->drawImage(image, 0, 0);
515##
516
517#SeeAlso MakeFromBackendTexture MakeRenderTarget
518
519#Method ##
520
521# ------------------------------------------------------------------------------
522
Cary Clarkf059e7c2017-12-20 14:53:21 -0500523#Method static sk_sp<SkSurface> MakeFromBackendRenderTarget(GrContext* context,
524 const GrBackendRenderTarget& backendRenderTarget,
525 GrSurfaceOrigin origin,
526 SkColorType colorType,
527 sk_sp<SkColorSpace> colorSpace,
528 const SkSurfaceProps* surfaceProps)
529
530Wraps a GPU-backed buffer into Surface. Caller must ensure render target is
531valid for the lifetime of returned Surface.
532
533Surface is returned if all parameters are valid. backendRenderTarget is valid if
534its pixel configuration agrees with colorSpace and context; for instance, if
535backendRenderTarget has an sRGB configuration, then context must support sRGB,
536and colorSpace must be present. Further, backendRenderTarget width and height must
537not exceed context capabilities, and the context must be able to support
538back-end render targets.
539
540If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
541
542#Param context GPU_Context ##
543#Param backendRenderTarget GPU intermediate memory buffer ##
544#Param origin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin ##
545#Param colorType one of: kUnknown_SkColorType, kAlpha_8_SkColorType,
546 kRGB_565_SkColorType, kARGB_4444_SkColorType,
547 kRGBA_8888_SkColorType, kBGRA_8888_SkColorType,
548 kGray_8_SkColorType, kRGBA_F16_SkColorType
549##
550#Param colorSpace range of colors ##
551#Param surfaceProps LCD striping orientation and setting for device independent
552 fonts; may be nullptr
553##
554
555#Return Surface if all parameters are valid; otherwise, nullptr ##
556
557#Example
558#ToDo remove !fiddle below once backEndTextureRenderTarget is available ##
559#Platform !fiddle gpu
560 SkPaint paint;
561 paint.setTextSize(32);
562 GrContext* context = canvas->getGrContext();
563 if (!context) {
564 canvas->drawString("GPU only!", 20, 40, paint);
565 return;
566 }
567 sk_sp<SkSurface> gpuSurface = SkSurface::MakeFromBackendRenderTarget(context,
568 backEndRenderTarget, kTopLeft_GrSurfaceOrigin, kRGBA_8888_SkColorType,
569 nullptr, nullptr);
570 auto surfaceCanvas = gpuSurface->getCanvas();
571 surfaceCanvas->clear(SK_ColorWHITE);
572 surfaceCanvas->drawString("GPU rocks!", 20, 40, paint);
573 sk_sp<SkImage> image(gpuSurface->makeImageSnapshot());
574 canvas->drawImage(image, 0, 0);
575##
576
577#SeeAlso MakeFromBackendTexture MakeRenderTarget
578
579#Method ##
580
581# ------------------------------------------------------------------------------
582
Cary Clarka560c472017-11-27 10:44:06 -0500583#Method static sk_sp<SkSurface> MakeFromBackendTextureAsRenderTarget(GrContext* context,
584 const GrBackendTexture& backendTexture,
585 GrSurfaceOrigin origin,
586 int sampleCnt,
587 sk_sp<SkColorSpace> colorSpace,
588 const SkSurfaceProps* surfaceProps)
Cary Clark4855f782018-02-06 09:41:53 -0500589#In Constructor
Cary Clarkab2621d2018-01-30 10:08:57 -0500590#Line # creates Surface from GPU-backed texture ##
Cary Clarka560c472017-11-27 10:44:06 -0500591
592Used to wrap a GPU-backed texture as a SkSurface. Skia will treat the texture as
593a rendering target only, but unlike NewFromBackendRenderTarget, Skia will manage and own
594the associated render target objects (but not the provided texture). Skia will not assume
595ownership of the texture and the client must ensure the texture is valid for the lifetime
596of the SkSurface.
597
598If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
599
600#Param context GPU_Context ##
601#Param backendTexture texture residing on GPU ##
602#Param origin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin ##
603#Param sampleCnt samples per pixel, or 0 to disable full scene anti-aliasing ##
604#Param colorSpace range of colors ##
605#Param surfaceProps LCD striping orientation and setting for device independent
606 fonts; may be nullptr
607##
608
609#Return Surface if all parameters are valid; otherwise, nullptr ##
610
611#Example
612#Platform !fiddle gpu
613 SkPaint paint;
614 paint.setTextSize(32);
615 GrContext* context = canvas->getGrContext();
616 if (!context) {
617 canvas->drawString("GPU only!", 20, 40, paint);
618 return;
619 }
620 sk_sp<SkSurface> gpuSurface = SkSurface::MakeFromBackendTextureAsRenderTarget(
621 context, backEndTextureRenderTarget, kTopLeft_GrSurfaceOrigin, 0,
622 nullptr, nullptr);
623 auto surfaceCanvas = gpuSurface->getCanvas();
624 surfaceCanvas->clear(SK_ColorWHITE);
625 surfaceCanvas->drawString("GPU rocks!", 20, 40, paint);
626 sk_sp<SkImage> image(gpuSurface->makeImageSnapshot());
627 canvas->drawImage(image, 0, 0);
628##
629
630#SeeAlso MakeFromBackendRenderTarget MakeRenderTarget
631
632#Method ##
633
634# ------------------------------------------------------------------------------
635
Cary Clarkf059e7c2017-12-20 14:53:21 -0500636#Method static sk_sp<SkSurface> MakeFromBackendTextureAsRenderTarget(GrContext* context,
637 const GrBackendTexture& backendTexture,
638 GrSurfaceOrigin origin,
639 int sampleCnt,
640 SkColorType colorType,
641 sk_sp<SkColorSpace> colorSpace,
642 const SkSurfaceProps* surfaceProps)
643
644Used to wrap a GPU-backed texture as a SkSurface. Skia will treat the texture as
645a rendering target only, but unlike NewFromBackendRenderTarget, Skia will manage and own
646the associated render target objects (but not the provided texture). Skia will not assume
647ownership of the texture and the client must ensure the texture is valid for the lifetime
648of the SkSurface.
649
650If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
651
652#Param context GPU_Context ##
653#Param backendTexture texture residing on GPU ##
654#Param origin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin ##
655#Param sampleCnt samples per pixel, or 0 to disable full scene anti-aliasing ##
656#Param colorType one of: kUnknown_SkColorType, kAlpha_8_SkColorType,
657 kRGB_565_SkColorType, kARGB_4444_SkColorType,
658 kRGBA_8888_SkColorType, kBGRA_8888_SkColorType,
659 kGray_8_SkColorType, kRGBA_F16_SkColorType
660##
661#Param colorSpace range of colors ##
662#Param surfaceProps LCD striping orientation and setting for device independent
663 fonts; may be nullptr
664##
665
666#Return Surface if all parameters are valid; otherwise, nullptr ##
667
668#Example
669#Platform !fiddle gpu
670 SkPaint paint;
671 paint.setTextSize(32);
672 GrContext* context = canvas->getGrContext();
673 if (!context) {
674 canvas->drawString("GPU only!", 20, 40, paint);
675 return;
676 }
677 sk_sp<SkSurface> gpuSurface = SkSurface::MakeFromBackendTextureAsRenderTarget(
678 context, backEndTextureRenderTarget, kTopLeft_GrSurfaceOrigin, 0,
679 kRGBA_8888_SkColorType, nullptr, nullptr);
680 auto surfaceCanvas = gpuSurface->getCanvas();
681 surfaceCanvas->clear(SK_ColorWHITE);
682 surfaceCanvas->drawString("GPU rocks!", 20, 40, paint);
683 sk_sp<SkImage> image(gpuSurface->makeImageSnapshot());
684 canvas->drawImage(image, 0, 0);
685##
686
687#SeeAlso MakeFromBackendRenderTarget MakeRenderTarget
688
689#Method ##
690
691# ------------------------------------------------------------------------------
692
Cary Clarka560c472017-11-27 10:44:06 -0500693#Method static sk_sp<SkSurface> MakeRenderTarget(GrContext* context, SkBudgeted budgeted,
694 const SkImageInfo& imageInfo,
695 int sampleCount, GrSurfaceOrigin surfaceOrigin,
696 const SkSurfaceProps* surfaceProps,
697 bool shouldCreateWithMips = false)
Cary Clark4855f782018-02-06 09:41:53 -0500698#In Constructor
Cary Clarkab2621d2018-01-30 10:08:57 -0500699#Line # creates Surface pointing to new GPU memory buffer ##
Cary Clarka560c472017-11-27 10:44:06 -0500700
Cary Clark4855f782018-02-06 09:41:53 -0500701Returns Surface on GPU indicated by context. Allocates memory for
Cary Clark2dc84ad2018-01-26 12:56:22 -0500702pixels, based on the width, height, and Color_Type in ImageInfo. budgeted
Cary Clark4855f782018-02-06 09:41:53 -0500703selects whether allocation for pixels is tracked by context. imageInfo
Cary Clark2dc84ad2018-01-26 12:56:22 -0500704describes the pixel format in Color_Type, and transparency in
705Alpha_Type, and color matching in Color_Space.
Cary Clarka560c472017-11-27 10:44:06 -0500706
707sampleCount requests the number of samples per pixel.
708Pass zero to disable Multi_Sample_Anti_Aliasing. The request is rounded
709up to the next supported count, or rounded down if it is larger than the
710maximum supported count.
711
712surfaceOrigin pins either the top-left or the bottom-left corner to the origin.
713
714shouldCreateWithMips hints that Image returned by makeImageSnapshot is Mip_Map.
715
716If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
717
718#Param context GPU_Context ##
719#Param budgeted one of: SkBudgeted::kNo, SkBudgeted::kYes ##
Cary Clark2dc84ad2018-01-26 12:56:22 -0500720#Param imageInfo width, height, Color_Type, Alpha_Type, Color_Space;
Cary Clarka560c472017-11-27 10:44:06 -0500721 width, or height, or both, may be zero
722##
723#Param sampleCount samples per pixel, or 0 to disable full scene anti-aliasing ##
724#Param surfaceOrigin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin ##
725#Param surfaceProps LCD striping orientation and setting for device independent
726 fonts; may be nullptr
727##
728#Param shouldCreateWithMips hint that Surface will host Mip_Map images ##
729
730#Return Surface if all parameters are valid; otherwise, nullptr ##
731
732#ToDo not sure that this example is relevant; surfaceOrigin doesn't appear to do anything ##
733#Example
734#Platform gpu
735#Height 64
736 SkPaint paint;
737 paint.setTextSize(32);
738 GrContext* context = canvas->getGrContext();
739 if (!context) {
740 canvas->drawString("GPU only!", 20, 40, paint);
741 return;
742 }
743 SkImageInfo info = SkImageInfo::MakeN32(256, 64, kOpaque_SkAlphaType);
744 for (auto surfaceOrigin : { kTopLeft_GrSurfaceOrigin, kBottomLeft_GrSurfaceOrigin } ) {
745 auto gpuSurface(SkSurface::MakeRenderTarget(context, SkBudgeted::kNo, info, 0,
746 surfaceOrigin, nullptr));
747 auto surfaceCanvas = gpuSurface->getCanvas();
748 surfaceCanvas->clear(SK_ColorWHITE);
749 surfaceCanvas->drawString("GPU rocks!", 20, 40, paint);
750 sk_sp<SkImage> image(gpuSurface->makeImageSnapshot());
751 canvas->drawImage(image, 0, 0);
752 canvas->translate(0, 128);
753 }
754##
755
756#SeeAlso MakeFromBackendRenderTarget MakeFromBackendTextureAsRenderTarget
757
758#Method ##
759
760# ------------------------------------------------------------------------------
761
762#Method static sk_sp<SkSurface> MakeRenderTarget(GrContext* context, SkBudgeted budgeted,
763 const SkImageInfo& imageInfo, int sampleCount,
764 const SkSurfaceProps* props)
765
Cary Clark4855f782018-02-06 09:41:53 -0500766Returns Surface on GPU indicated by context. Allocates memory for
Cary Clark2dc84ad2018-01-26 12:56:22 -0500767pixels, based on the width, height, and Color_Type in ImageInfo. budgeted
Cary Clark4855f782018-02-06 09:41:53 -0500768selects whether allocation for pixels is tracked by context. imageInfo
Cary Clark2dc84ad2018-01-26 12:56:22 -0500769describes the pixel format in Color_Type, and transparency in
770Alpha_Type, and color matching in Color_Space.
Cary Clarka560c472017-11-27 10:44:06 -0500771
772sampleCount requests the number of samples per pixel.
773Pass zero to disable Multi_Sample_Anti_Aliasing. The request is rounded
774up to the next supported count, or rounded down if it is larger than the
775maximum supported count.
776
777Surface bottom-left corner is pinned to the origin.
778
779#Param context GPU_Context ##
780#Param budgeted one of: SkBudgeted::kNo, SkBudgeted::kYes ##
Cary Clark2dc84ad2018-01-26 12:56:22 -0500781#Param imageInfo width, height, Color_Type, Alpha_Type, Color_Space,
Cary Clarka560c472017-11-27 10:44:06 -0500782 of Raster_Surface; width, or height, or both, may be zero
783##
784#Param sampleCount samples per pixel, or 0 to disable Multi_Sample_Anti_Aliasing ##
785#Param props LCD striping orientation and setting for device independent
786 fonts; may be nullptr
787##
788
789#Return Surface if all parameters are valid; otherwise, nullptr ##
790
791#Example
Cary Clark3cd22cc2017-12-01 11:49:58 -0500792#Platform cpu gpu
Cary Clarka560c472017-11-27 10:44:06 -0500793#Description
794LCD text takes advantage of raster striping to improve resolution. Only one of
Cary Clark4855f782018-02-06 09:41:53 -0500795the four combinations is correct, depending on whether monitor LCD striping is
Cary Clarka560c472017-11-27 10:44:06 -0500796horizontal or vertical, and whether the order of the stripes is red blue green
797or red green blue.
798##
799void draw(SkCanvas* canvas) {
800 auto test_draw = [](SkCanvas* surfaceCanvas) -> void {
801 SkPaint paint;
802 paint.setAntiAlias(true);
803 paint.setLCDRenderText(true);
804 paint.setColor(0xFFBBBBBB);
805 surfaceCanvas->drawRect(SkRect::MakeWH(128, 64), paint);
806 paint.setColor(SK_ColorWHITE);
807 paint.setTextSize(32);
808 surfaceCanvas->drawString("Pest", 0, 25, paint);
809 };
810 GrContext* context = canvas->getGrContext();
811 SkImageInfo info = SkImageInfo::MakeN32(128, 64, kOpaque_SkAlphaType);
Cary Clarka560c472017-11-27 10:44:06 -0500812 int y = 0;
813 for (auto geometry : { kRGB_H_SkPixelGeometry, kBGR_H_SkPixelGeometry,
814 kRGB_V_SkPixelGeometry, kBGR_V_SkPixelGeometry } ) {
815 SkSurfaceProps props(0, geometry);
Cary Clarka560c472017-11-27 10:44:06 -0500816 sk_sp<SkSurface> surface = context ? SkSurface::MakeRenderTarget(
817 context, SkBudgeted::kNo, info, 0, &props) : SkSurface::MakeRaster(info, &props);
818 test_draw(surface->getCanvas());
819 surface->draw(canvas, 0, y, nullptr);
Cary Clark3cd22cc2017-12-01 11:49:58 -0500820 sk_sp<SkImage> image(surface->makeImageSnapshot());
Cary Clarka560c472017-11-27 10:44:06 -0500821 SkAutoCanvasRestore acr(canvas, true);
822 canvas->scale(8, 8);
Cary Clark3cd22cc2017-12-01 11:49:58 -0500823 canvas->drawImage(image, 12, y / 8);
Cary Clarka560c472017-11-27 10:44:06 -0500824 y += 64;
825 }
826}
827##
828
829#SeeAlso MakeFromBackendRenderTarget MakeFromBackendTextureAsRenderTarget
830
831#Method ##
832
833# ------------------------------------------------------------------------------
834
835#Method static sk_sp<SkSurface> MakeRenderTarget(GrContext* context, SkBudgeted budgeted,
836 const SkImageInfo& imageInfo)
837
Cary Clark4855f782018-02-06 09:41:53 -0500838Returns Surface on GPU indicated by context. Allocates memory for
Cary Clark2dc84ad2018-01-26 12:56:22 -0500839pixels, based on the width, height, and Color_Type in ImageInfo. budgeted
Cary Clark4855f782018-02-06 09:41:53 -0500840selects whether allocation for pixels is tracked by context. imageInfo
Cary Clark2dc84ad2018-01-26 12:56:22 -0500841describes the pixel format in Color_Type, and transparency in
842Alpha_Type, and color matching in Color_Space.
Cary Clarka560c472017-11-27 10:44:06 -0500843
844Surface bottom-left corner is pinned to the origin.
845
846#Param context GPU_Context ##
847#Param budgeted one of: SkBudgeted::kNo, SkBudgeted::kYes ##
Cary Clark2dc84ad2018-01-26 12:56:22 -0500848#Param imageInfo width, height, Color_Type, Alpha_Type, Color_Space,
Cary Clarka560c472017-11-27 10:44:06 -0500849 of Raster_Surface; width, or height, or both, may be zero
850##
851
852#Return Surface if all parameters are valid; otherwise, nullptr ##
853
854#Example
855#Platform gpu
856 SkPaint paint;
857 paint.setTextSize(32);
858 GrContext* context = canvas->getGrContext();
859 if (!context) {
860 canvas->drawString("GPU only!", 20, 40, paint);
861 return;
862 }
863 SkImageInfo info = SkImageInfo::MakeN32(256, 64, kOpaque_SkAlphaType);
864 auto gpuSurface(SkSurface::MakeRenderTarget(context, SkBudgeted::kNo, info));
865 auto surfaceCanvas = gpuSurface->getCanvas();
866 surfaceCanvas->clear(SK_ColorWHITE);
867 surfaceCanvas->drawString("GPU rocks!", 20, 40, paint);
868 sk_sp<SkImage> image(gpuSurface->makeImageSnapshot());
869 canvas->drawImage(image, 0, 0);
870##
871
872#SeeAlso MakeFromBackendRenderTarget MakeFromBackendTextureAsRenderTarget
873
874#Method ##
875
876# ------------------------------------------------------------------------------
877
878#Method static sk_sp<SkSurface> MakeNull(int width, int height)
879
Cary Clark4855f782018-02-06 09:41:53 -0500880#In Constructor
Cary Clarkab2621d2018-01-30 10:08:57 -0500881#Line # creates Surface without backing pixels ##
Cary Clarka560c472017-11-27 10:44:06 -0500882Returns Surface without backing pixels. Drawing to Canvas returned from Surface
883has no effect. Calling makeImageSnapshot() on returned Surface returns nullptr.
884
885#Param width one or greater ##
886#Param height one or greater ##
887
888#Return Surface if width and height are positive; otherwise, nullptr ##
889
890#Example
891 SkDebugf("SkSurface::MakeNull(0, 0) %c= nullptr\n", SkSurface::MakeNull(0, 0) == nullptr ?
892 '=' : '!');
893 const int w = 37;
894 const int h = 1000;
895 auto surf = SkSurface::MakeNull(w, h);
896 auto nullCanvas = surf->getCanvas();
897 nullCanvas->drawPaint(SkPaint()); // does not crash, nothing draws
898 SkDebugf("surf->makeImageSnapshot() %c= nullptr\n", surf->makeImageSnapshot() == nullptr ?
899 '=' : '!');
900#StdOut
901SkSurface::MakeNull(0, 0) == nullptr
902surf->makeImageSnapshot() == nullptr
903##
904##
905
906#SeeAlso MakeRaster MakeRenderTarget
907
908#Method ##
909
910# ------------------------------------------------------------------------------
Cary Clark4855f782018-02-06 09:41:53 -0500911#Subtopic Property
912#Populate
913#Line # member values ##
914##
Cary Clarka560c472017-11-27 10:44:06 -0500915
916#Method int width() const
917
Cary Clark4855f782018-02-06 09:41:53 -0500918#In Property
Cary Clarkab2621d2018-01-30 10:08:57 -0500919#Line # returns pixel column count ##
Cary Clarka560c472017-11-27 10:44:06 -0500920Returns pixel count in each row; may be zero or greater.
921
922#Return number of pixel columns ##
923
924#Example
925 const int width = 37;
926 const int height = 1000;
927 auto surf = SkSurface::MakeNull(width, height);
928 auto nullCanvas = surf->getCanvas();
929 SkDebugf("surface width=%d canvas width=%d\n", surf->width(),
930 nullCanvas->getBaseLayerSize().fWidth);
931#StdOut
932surface width=37 canvas width=37
933##
934##
935
936#SeeAlso height()
937
938#Method ##
939
940# ------------------------------------------------------------------------------
941
942#Method int height() const
Cary Clark4855f782018-02-06 09:41:53 -0500943#In Property
Cary Clarkab2621d2018-01-30 10:08:57 -0500944#Line # returns pixel row count ##
Cary Clarka560c472017-11-27 10:44:06 -0500945Returns pixel row count; may be zero or greater.
946
947#Return number of pixel rows ##
948
949#Example
950 const int width = 37;
951 const int height = 1000;
952 auto surf = SkSurface::MakeNull(width, height);
953 auto nullCanvas = surf->getCanvas();
954 SkDebugf("surface height=%d canvas height=%d\n", surf->height(),
955 nullCanvas->getBaseLayerSize().fHeight);
956#StdOut
957surface height=1000 canvas height=1000
958##
959##
960
961#SeeAlso width()
962
963#Method ##
964
965# ------------------------------------------------------------------------------
966
967#Method uint32_t generationID()
Cary Clark4855f782018-02-06 09:41:53 -0500968#In Property
Cary Clarkab2621d2018-01-30 10:08:57 -0500969#Line # returns unique ID ##
Cary Clarka560c472017-11-27 10:44:06 -0500970Returns unique value identifying the content of Surface. Returned value changes
971each time the content changes. Content is changed by drawing, or by calling
972notifyContentWillChange.
973
974#Return unique content identifier ##
975
976#Example
977 auto surface = SkSurface::MakeRasterN32Premul(1, 1);
978 for (int i = 0; i < 3; ++i) {
979 SkDebugf("surface generationID: %d\n", surface->generationID());
980 if (0 == i) {
981 surface->getCanvas()->drawColor(SK_ColorBLACK);
982 } else {
983 surface->notifyContentWillChange(SkSurface::kDiscard_ContentChangeMode);
984 }
985 }
986#StdOut
987surface generationID: 1
988surface generationID: 2
989surface generationID: 3
990##
991##
992
993#SeeAlso notifyContentWillChange ContentChangeMode getCanvas
994
995#Method ##
996
997# ------------------------------------------------------------------------------
998
999#Enum ContentChangeMode
1000
1001#Code
1002 enum ContentChangeMode {
1003 kDiscard_ContentChangeMode,
1004 kRetain_ContentChangeMode,
1005 };
1006##
1007
1008ContentChangeMode members are parameters to notifyContentWillChange.
1009
1010#Const kDiscard_ContentChangeMode
1011Pass to notifyContentWillChange to discard surface contents when
1012the surface is cleared or overwritten.
1013##
1014#Const kRetain_ContentChangeMode
1015Pass to notifyContentWillChange when to preserve surface contents.
1016If a snapshot has been generated, this copies the Surface contents.
1017##
1018
1019#SeeAlso notifyContentWillChange generationID
1020
1021#Enum ##
1022
1023# ------------------------------------------------------------------------------
1024
Cary Clark4855f782018-02-06 09:41:53 -05001025#ToDo not crazy about misc catagory -- hopefully will become clear with time
1026##
Cary Clarka560c472017-11-27 10:44:06 -05001027
Cary Clark4855f782018-02-06 09:41:53 -05001028#Subtopic Miscellaneous
1029#Populate
1030#Line # other functions ##
1031##
1032
1033#Method void notifyContentWillChange(ContentChangeMode mode)
1034#In Miscellaneous
Cary Clarkab2621d2018-01-30 10:08:57 -05001035#Line # notifies that contents will be changed outside of Skia ##
Cary Clarka560c472017-11-27 10:44:06 -05001036Notifies that Surface contents will be changed by code outside of Skia.
1037Subsequent calls to generationID return a different value.
1038
1039mode is normally passed as kRetain_ContentChangeMode.
1040
1041#Private
1042CAN WE DEPRECATE THIS?
1043##
1044
1045#Param mode one of: kDiscard_ContentChangeMode, kRetain_ContentChangeMode ##
1046
1047#Example
1048 auto surface = SkSurface::MakeRasterN32Premul(1, 1);
1049 for (int i = 0; i < 3; ++i) {
1050 SkDebugf("surface generationID: %d\n", surface->generationID());
1051 if (0 == i) {
1052 surface->getCanvas()->drawColor(SK_ColorBLACK);
1053 } else {
1054 surface->notifyContentWillChange(SkSurface::kDiscard_ContentChangeMode);
1055 }
1056 }
1057##
1058
1059#SeeAlso ContentChangeMode generationID
1060
1061#Method ##
1062
1063# ------------------------------------------------------------------------------
1064
1065#Enum BackendHandleAccess
1066
1067#Code
1068 enum BackendHandleAccess {
1069 kFlushRead_BackendHandleAccess,
1070 kFlushWrite_BackendHandleAccess,
1071 kDiscardWrite_BackendHandleAccess,
1072 };
Cary Clark7cfcbca2018-01-04 16:11:51 -05001073
1074 static const BackendHandleAccess kFlushRead_TextureHandleAccess =
1075 kFlushRead_BackendHandleAccess;
1076 static const BackendHandleAccess kFlushWrite_TextureHandleAccess =
1077 kFlushWrite_BackendHandleAccess;
1078 static const BackendHandleAccess kDiscardWrite_TextureHandleAccess =
1079 kDiscardWrite_BackendHandleAccess;
Cary Clarka560c472017-11-27 10:44:06 -05001080##
1081
Cary Clark3cd22cc2017-12-01 11:49:58 -05001082#Const kFlushRead_BackendHandleAccess 0
Cary Clarka560c472017-11-27 10:44:06 -05001083Caller may read from the back-end object.
1084##
Cary Clark3cd22cc2017-12-01 11:49:58 -05001085#Const kFlushWrite_BackendHandleAccess 1
Cary Clarka560c472017-11-27 10:44:06 -05001086Caller may write to the back-end object.
1087##
Cary Clark3cd22cc2017-12-01 11:49:58 -05001088#Const kDiscardWrite_BackendHandleAccess 2
Cary Clarka560c472017-11-27 10:44:06 -05001089Caller must overwrite the entire back-end object.
1090##
1091
Cary Clark7cfcbca2018-01-04 16:11:51 -05001092#Const kFlushRead_TextureHandleAccess 0
Cary Clark7cfcbca2018-01-04 16:11:51 -05001093#Deprecated
1094##
Cary Clark7cfcbca2018-01-04 16:11:51 -05001095#Const kFlushWrite_TextureHandleAccess 1
Cary Clark7cfcbca2018-01-04 16:11:51 -05001096#Deprecated
1097##
Cary Clark7cfcbca2018-01-04 16:11:51 -05001098#Const kDiscardWrite_TextureHandleAccess 2
Cary Clark7cfcbca2018-01-04 16:11:51 -05001099#Deprecated
1100##
Cary Clark7cfcbca2018-01-04 16:11:51 -05001101
Cary Clarka560c472017-11-27 10:44:06 -05001102#Example
1103#Platform gpu
Cary Clark3cd22cc2017-12-01 11:49:58 -05001104 SkPaint paint;
1105 paint.setTextSize(32);
1106 GrContext* context = canvas->getGrContext();
1107 if (!context) {
1108 canvas->drawString("GPU only!", 20, 40, paint);
1109 return;
1110 }
1111 sk_sp<SkSurface> gpuSurface = SkSurface::MakeRenderTarget(
1112 context, SkBudgeted::kYes, SkImageInfo::MakeN32Premul(10, 10));
1113 int y = 20;
1114 SkString str;
1115 paint.setTextSize(16);
1116 for (auto access : { SkSurface::kFlushRead_BackendHandleAccess,
1117 SkSurface::kFlushWrite_BackendHandleAccess,
1118 SkSurface::kDiscardWrite_BackendHandleAccess } ) {
1119 sk_sp<SkImage> image(gpuSurface->makeImageSnapshot());
1120 str.printf("uniqueID=%d", image->uniqueID());
1121 canvas->drawString(str, 20, y += 20, paint);
1122 GrBackendObject backendObject = gpuSurface->getTextureHandle(access);
1123 str.printf("backendObject %c= 0", backendObject != 0 ? '!' : '=');
1124 canvas->drawString(str, 20, y += 20, paint);
1125 }
1126 sk_sp<SkImage> image(gpuSurface->makeImageSnapshot());
1127 str.printf("final image uniqueID=%d", image->uniqueID());
1128 canvas->drawString(str, 20, y += 20, paint);
Cary Clarka560c472017-11-27 10:44:06 -05001129##
1130
1131#SeeAlso getTextureHandle getRenderTargetHandle
1132
1133#Enum ##
1134
1135# ------------------------------------------------------------------------------
1136
1137#Method GrBackendObject getTextureHandle(BackendHandleAccess backendHandleAccess)
Cary Clark4855f782018-02-06 09:41:53 -05001138#In Property
Cary Clarkab2621d2018-01-30 10:08:57 -05001139#Line # returns the GPU reference to texture ##
Cary Clarka560c472017-11-27 10:44:06 -05001140Returns the GPU back-end reference of the texture used by Surface, or zero
1141if Surface is not backed by a GPU texture.
1142
1143The returned texture handle is only valid until the next draw into Surface,
1144or when Surface is deleted.
1145
1146#Param backendHandleAccess one of: kFlushRead_BackendHandleAccess,
1147 kFlushWrite_BackendHandleAccess, kDiscardWrite_BackendHandleAccess
1148##
1149
1150#Return GPU texture reference ##
1151
1152#Example
1153#Platform gpu
1154#Height 64
Cary Clark3cd22cc2017-12-01 11:49:58 -05001155 SkPaint paint;
1156 paint.setTextSize(32);
1157 GrContext* context = canvas->getGrContext();
1158 if (!context) {
1159 canvas->drawString("GPU only!", 20, 40, paint);
1160 return;
1161 }
1162 sk_sp<SkSurface> gpuSurface = SkSurface::MakeRenderTarget(
1163 context, SkBudgeted::kYes, SkImageInfo::MakeN32Premul(10, 10));
1164 GrBackendObject backendObject = gpuSurface->getTextureHandle(
1165 SkSurface::kFlushRead_BackendHandleAccess);
1166 if (backendObject) {
1167 SkString str;
1168 str.printf("backendObject=%08x", backendObject);
1169 paint.setTextSize(16);
1170 canvas->drawString(str, 20, 40, paint);
1171 }
Cary Clarka560c472017-11-27 10:44:06 -05001172##
1173
1174#SeeAlso getRenderTargetHandle GrBackendObject BackendHandleAccess
1175
1176#Method ##
1177
1178# ------------------------------------------------------------------------------
1179
1180#Method bool getRenderTargetHandle(GrBackendObject* backendObject,
1181 BackendHandleAccess backendHandleAccess)
Cary Clark4855f782018-02-06 09:41:53 -05001182#In Property
Cary Clarkab2621d2018-01-30 10:08:57 -05001183#Line # returns the GPU reference to render target ##
Cary Clarka560c472017-11-27 10:44:06 -05001184
1185Returns true and stores the GPU back-end reference of the render target used
1186by Surface in backendObject.
1187
1188Return false if Surface is not backed by a GPU render target, and leaves
1189backendObject unchanged.
1190
1191The returned render target handle is only valid until the next draw into Surface,
1192or when Surface is deleted.
1193
1194In OpenGL this returns the frame buffer object ID.
1195
1196#Param backendObject GPU intermediate memory buffer ##
1197#Param backendHandleAccess one of: kFlushRead_BackendHandleAccess,
1198 kFlushWrite_BackendHandleAccess, kDiscardWrite_BackendHandleAccess
1199##
1200
1201#Return true if Surface is backed by GPU texture ##
1202
1203#Example
1204#Platform gpu
1205#Height 64
Cary Clark3cd22cc2017-12-01 11:49:58 -05001206 SkPaint paint;
1207 paint.setTextSize(32);
1208 GrContext* context = canvas->getGrContext();
1209 if (!context) {
1210 canvas->drawString("GPU only!", 20, 40, paint);
1211 return;
1212 }
1213 sk_sp<SkSurface> gpuSurface = SkSurface::MakeRenderTarget(
1214 context, SkBudgeted::kYes, SkImageInfo::MakeN32Premul(10, 10));
1215 GrBackendObject backendObject;
1216 if (gpuSurface->getRenderTargetHandle(&backendObject,
1217 SkSurface::kFlushRead_BackendHandleAccess)) {
1218 SkString str;
1219 str.printf("backendObject=%d", backendObject);
1220 paint.setTextSize(16);
1221 canvas->drawString(str, 20, 40, paint);
1222 }
Cary Clarka560c472017-11-27 10:44:06 -05001223##
1224
1225#SeeAlso getTextureHandle GrBackendObject BackendHandleAccess
1226
1227#Method ##
1228
1229# ------------------------------------------------------------------------------
1230
1231#Method SkCanvas* getCanvas()
Cary Clark4855f782018-02-06 09:41:53 -05001232#In Property
Cary Clarkab2621d2018-01-30 10:08:57 -05001233#Line # returns Canvas that draws into Surface ##
Cary Clarka560c472017-11-27 10:44:06 -05001234Returns Canvas that draws into Surface. Subsequent calls return the same Canvas.
1235Canvas returned is managed and owned by Surface, and is deleted when Surface
1236is deleted.
1237
1238#Return drawing Canvas for Surface ##
1239
1240#Example
1241#Height 64
1242 sk_sp<SkSurface> surface(SkSurface::MakeRasterN32Premul(64, 64));
1243 SkCanvas* surfaceCanvas = surface->getCanvas();
1244 surfaceCanvas->clear(SK_ColorBLUE);
1245 SkPaint paint;
1246 paint.setTextSize(40);
1247 surfaceCanvas->drawString("\xF0\x9F\x98\x81", 12, 45, paint);
1248 surface->draw(canvas, 0, 0, nullptr);
1249##
1250
Cary Clark4855f782018-02-06 09:41:53 -05001251#SeeAlso makeSurface makeImageSnapshot draw
Cary Clarka560c472017-11-27 10:44:06 -05001252
1253#Method ##
1254
1255# ------------------------------------------------------------------------------
1256
1257#Method sk_sp<SkSurface> makeSurface(const SkImageInfo& imageInfo)
Cary Clark4855f782018-02-06 09:41:53 -05001258#In Constructor
Cary Clarkab2621d2018-01-30 10:08:57 -05001259#Line # creates a compatible Surface ##
Cary Clarka560c472017-11-27 10:44:06 -05001260Returns a compatible Surface, or nullptr. Returned Surface contains
1261the same raster, GPU, or null properties as the original. Returned Surface
1262does not share the same pixels.
1263
1264Returns nullptr if imageInfo width or height are zero, or if imageInfo
1265is incompatible with Surface.
1266
Cary Clark2dc84ad2018-01-26 12:56:22 -05001267#Param imageInfo width, height, Color_Type, Alpha_Type, Color_Space,
Cary Clarka560c472017-11-27 10:44:06 -05001268 of Surface; width and height must be greater than zero
1269##
1270
1271#Return compatible Surface or nullptr ##
1272
1273#Example
1274#Height 96
1275 sk_sp<SkSurface> big(SkSurface::MakeRasterN32Premul(64, 64));
1276 sk_sp<SkSurface> lil(big->makeSurface(SkImageInfo::MakeN32(32, 32, kPremul_SkAlphaType)));
1277 big->getCanvas()->clear(SK_ColorRED);
1278 lil->getCanvas()->clear(SK_ColorBLACK);
1279 SkPixmap pixmap;
1280 if (big->peekPixels(&pixmap)) {
1281 SkBitmap bigBits;
1282 bigBits.installPixels(pixmap);
1283 canvas->drawBitmap(bigBits, 0, 0);
1284 }
1285 if (lil->peekPixels(&pixmap)) {
1286 SkBitmap lilBits;
1287 lilBits.installPixels(pixmap);
1288 canvas->drawBitmap(lilBits, 64, 64);
1289 }
1290##
1291
Cary Clark4855f782018-02-06 09:41:53 -05001292#SeeAlso makeImageSnapshot getCanvas draw
Cary Clarka560c472017-11-27 10:44:06 -05001293
1294#Method ##
1295
1296# ------------------------------------------------------------------------------
1297
1298#Method sk_sp<SkImage> makeImageSnapshot()
Cary Clark4855f782018-02-06 09:41:53 -05001299#In Constructor
Cary Clarkab2621d2018-01-30 10:08:57 -05001300#Line # creates Image capturing Surface contents ##
Cary Clarka560c472017-11-27 10:44:06 -05001301Returns Image capturing Surface contents. Subsequent drawing to Surface contents
1302are not captured. Image allocation is accounted for if Surface was created with
1303SkBudgeted::kYes.
1304
1305#Return Image initialized with Surface contents ##
1306
1307#Example
1308#Height 64
1309 sk_sp<SkSurface> big(SkSurface::MakeRasterN32Premul(64, 64));
1310 sk_sp<SkSurface> lil(big->makeSurface(SkImageInfo::MakeN32(32, 32, kPremul_SkAlphaType)));
1311 big->getCanvas()->clear(SK_ColorRED);
1312 lil->getCanvas()->clear(SK_ColorBLACK);
1313 sk_sp<SkImage> early(big->makeImageSnapshot());
1314 lil->draw(big->getCanvas(), 16, 16, nullptr);
1315 sk_sp<SkImage> later(big->makeImageSnapshot());
1316 canvas->drawImage(early, 0, 0);
1317 canvas->drawImage(later, 128, 0);
1318##
1319
1320#SeeAlso draw getCanvas
1321
1322#Method ##
1323
1324# ------------------------------------------------------------------------------
Cary Clark4855f782018-02-06 09:41:53 -05001325#Subtopic Pixels
1326#Populate
1327#Line # functions with pixel access ##
1328##
Cary Clarka560c472017-11-27 10:44:06 -05001329
1330#Method void draw(SkCanvas* canvas, SkScalar x, SkScalar y, const SkPaint* paint)
Cary Clark4855f782018-02-06 09:41:53 -05001331#In Pixels
Cary Clarkab2621d2018-01-30 10:08:57 -05001332#Line # draws Surface contents to canvas ##
Cary Clarka560c472017-11-27 10:44:06 -05001333Draws Surface contents to canvas, with its top-left corner at (x, y).
1334
1335If Paint paint is not nullptr, apply Color_Filter, Color_Alpha, Image_Filter,
1336Blend_Mode, and Draw_Looper.
1337
1338#Param canvas Canvas drawn into ##
1339#Param x horizontal offset in Canvas ##
1340#Param y vertical offset in Canvas ##
1341#Param paint Paint containing Blend_Mode, Color_Filter, Image_Filter,
1342 and so on; or nullptr
1343##
1344
1345#Example
1346#Height 64
1347 sk_sp<SkSurface> big(SkSurface::MakeRasterN32Premul(64, 64));
1348 sk_sp<SkSurface> lil(big->makeSurface(SkImageInfo::MakeN32(32, 32, kPremul_SkAlphaType)));
1349 big->getCanvas()->clear(SK_ColorRED);
1350 lil->getCanvas()->clear(SK_ColorBLACK);
1351 lil->draw(big->getCanvas(), 16, 16, nullptr);
1352 SkPixmap pixmap;
1353 if (big->peekPixels(&pixmap)) {
1354 SkBitmap bigBits;
1355 bigBits.installPixels(pixmap);
1356 canvas->drawBitmap(bigBits, 0, 0);
1357 }
1358##
1359
1360#SeeAlso makeImageSnapshot getCanvas
1361
1362#Method ##
1363
1364# ------------------------------------------------------------------------------
1365
1366#Method bool peekPixels(SkPixmap* pixmap)
Cary Clark4855f782018-02-06 09:41:53 -05001367#In Pixels
Cary Clarkab2621d2018-01-30 10:08:57 -05001368#Line # copies Surface parameters to Pixmap ##
Cary Clarka560c472017-11-27 10:44:06 -05001369Copies Surface pixel address, row bytes, and Image_Info to Pixmap, if address
1370is available, and returns true. If pixel address is not available, return
1371false and leave Pixmap unchanged.
1372
1373pixmap contents become invalid on any future change to Surface.
1374
1375#Param pixmap storage for pixel state if pixels are readable; otherwise, ignored ##
1376
1377#Return true if Surface has direct access to pixels ##
1378
1379#Example
1380#Height 64
1381 sk_sp<SkSurface> surf(SkSurface::MakeRasterN32Premul(64, 64));
1382 auto surfCanvas = surf->getCanvas();
1383 surfCanvas->clear(SK_ColorRED);
1384 SkPaint paint;
1385 paint.setTextSize(40);
1386 surfCanvas->drawString("&", 16, 48, paint);
1387 SkPixmap pixmap;
1388 if (surf->peekPixels(&pixmap)) {
1389 SkBitmap surfBits;
1390 surfBits.installPixels(pixmap);
1391 canvas->drawBitmap(surfBits, 0, 0);
1392 }
1393##
1394
Mike Reed4c790bd2018-02-08 14:10:40 -05001395#SeeAlso readPixels writePixels
Cary Clarka560c472017-11-27 10:44:06 -05001396
1397#Method ##
1398
1399# ------------------------------------------------------------------------------
1400
1401#Method bool readPixels(const SkPixmap& dst, int srcX, int srcY)
Cary Clark4855f782018-02-06 09:41:53 -05001402#In Pixels
Cary Clarkab2621d2018-01-30 10:08:57 -05001403#Line # copies Rect of pixels ##
Cary Clarka560c472017-11-27 10:44:06 -05001404Copies Rect of pixels to dst.
1405
Cary Clarkac47b882018-01-11 10:35:44 -05001406Source Rect corners are (srcX, srcY) and Surface (width(), height()).
Cary Clarka560c472017-11-27 10:44:06 -05001407Destination Rect corners are (0, 0) and (dst.width(), dst.height()).
1408Copies each readable pixel intersecting both rectangles, without scaling,
1409converting to dst.colorType() and dst.alphaType() if required.
1410
1411Pixels are readable when Surface is raster, or backed by a GPU.
1412
1413The destination pixel storage must be allocated by the caller.
1414
Cary Clark2dc84ad2018-01-26 12:56:22 -05001415Pixel values are converted only if Color_Type and Alpha_Type
Cary Clarka560c472017-11-27 10:44:06 -05001416do not match. Only pixels within both source and destination rectangles
1417are copied. dst contents outside Rect intersection are unchanged.
1418
1419Pass negative values for srcX or srcY to offset pixels across or down destination.
1420
1421Does not copy, and returns false if:
1422
1423#List
1424# Source and destination rectangles do not intersect. ##
1425# Pixmap pixels could not be allocated. ##
1426# dst.rowBytes() is too small to contain one row of pixels. ##
1427##
1428
1429#Param dst storage for pixels copied from Surface ##
1430#Param srcX offset into readable pixels in x; may be negative ##
1431#Param srcY offset into readable pixels in y; may be negative ##
1432
1433#Return true if pixels were copied ##
1434
1435#Example
1436#Height 32
1437 sk_sp<SkSurface> surf(SkSurface::MakeRasterN32Premul(64, 64));
1438 auto surfCanvas = surf->getCanvas();
1439 surfCanvas->clear(SK_ColorRED);
1440 SkPaint paint;
1441 paint.setTextSize(40);
1442 surfCanvas->drawString("&", 0, 32, paint);
1443 std::vector<SkPMColor> storage;
1444 storage.resize(surf->width() * surf->height());
1445 SkPixmap pixmap(SkImageInfo::MakeN32Premul(32, 32), &storage.front(),
1446 surf->width() * sizeof(storage[0]));
1447 if (surf->readPixels(pixmap, 0, 0)) {
1448 SkBitmap surfBits;
1449 surfBits.installPixels(pixmap);
1450 canvas->drawBitmap(surfBits, 0, 0);
1451 }
1452##
1453
Mike Reed4c790bd2018-02-08 14:10:40 -05001454#SeeAlso peekPixels writePixels
Cary Clarka560c472017-11-27 10:44:06 -05001455
1456#Method ##
1457
1458# ------------------------------------------------------------------------------
1459
1460#Method bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes,
1461 int srcX, int srcY)
1462
1463Copies Rect of pixels from Canvas into dstPixels.
1464
Cary Clarkac47b882018-01-11 10:35:44 -05001465Source Rect corners are (srcX, srcY) and Surface (width(), height()).
Cary Clarka560c472017-11-27 10:44:06 -05001466Destination Rect corners are (0, 0) and (dstInfo.width(), dstInfo.height()).
1467Copies each readable pixel intersecting both rectangles, without scaling,
1468converting to dstInfo.colorType() and dstInfo.alphaType() if required.
1469
1470Pixels are readable when Surface is raster, or backed by a GPU.
1471
1472The destination pixel storage must be allocated by the caller.
1473
Cary Clark2dc84ad2018-01-26 12:56:22 -05001474Pixel values are converted only if Color_Type and Alpha_Type
Cary Clarka560c472017-11-27 10:44:06 -05001475do not match. Only pixels within both source and destination rectangles
1476are copied. dstPixels contents outside Rect intersection are unchanged.
1477
1478Pass negative values for srcX or srcY to offset pixels across or down destination.
1479
1480Does not copy, and returns false if:
1481
1482#List
1483# Source and destination rectangles do not intersect. ##
1484# Surface pixels could not be converted to dstInfo.colorType() or dstInfo.alphaType(). ##
1485# dstRowBytes is too small to contain one row of pixels. ##
1486##
1487
Cary Clark2dc84ad2018-01-26 12:56:22 -05001488#Param dstInfo width, height, Color_Type, and Alpha_Type of dstPixels ##
Cary Clarka560c472017-11-27 10:44:06 -05001489#Param dstPixels storage for pixels; dstInfo.height() times dstRowBytes, or larger ##
1490#Param dstRowBytes size of one destination row; dstInfo.width() times pixel size, or larger ##
1491#Param srcX offset into readable pixels in x; may be negative ##
1492#Param srcY offset into readable pixels in y; may be negative ##
1493
1494#Return true if pixels were copied ##
1495
1496#Example
1497#Height 64
1498#Description
1499 A black oval drawn on a red background provides an image to copy.
1500 readPixels copies one quarter of the Surface into each of the four corners.
1501 The copied quarter ovals overdraw the original oval.
1502##
1503 sk_sp<SkSurface> surf(SkSurface::MakeRasterN32Premul(64, 64));
1504 auto surfCanvas = surf->getCanvas();
1505 surfCanvas->clear(SK_ColorRED);
1506 SkPaint paint;
1507 surfCanvas->drawOval({4, 8, 58, 54}, paint);
1508 SkImageInfo info = SkImageInfo::Make(64, 64, kBGRA_8888_SkColorType, kPremul_SkAlphaType);
1509 sk_sp<SkData> data(SkData::MakeUninitialized(info.minRowBytes() * info.height()));
1510 sk_bzero(data->writable_data(), info.minRowBytes() * info.height());
1511 for (int x : { 32, -32 } ) {
1512 for (int y : { 32, -32 } ) {
1513 surf->readPixels(info, data->writable_data(), info.minRowBytes(), x, y);
1514 }
1515 }
1516 sk_sp<SkImage> image = SkImage::MakeRasterData(info, data, info.minRowBytes());
1517 canvas->drawImage(image, 0, 0);
1518##
1519
Mike Reed4c790bd2018-02-08 14:10:40 -05001520#SeeAlso peekPixels writePixels
Cary Clarka560c472017-11-27 10:44:06 -05001521
1522#Method ##
1523
1524# ------------------------------------------------------------------------------
1525
1526#Method bool readPixels(const SkBitmap& dst, int srcX, int srcY)
1527
1528Copies Rect of pixels from Surface into bitmap.
1529
Cary Clarkac47b882018-01-11 10:35:44 -05001530Source Rect corners are (srcX, srcY) and Surface (width(), height()).
Cary Clarka560c472017-11-27 10:44:06 -05001531Destination Rect corners are (0, 0) and (bitmap.width(), bitmap.height()).
1532Copies each readable pixel intersecting both rectangles, without scaling,
1533converting to bitmap.colorType() and bitmap.alphaType() if required.
1534
1535Pixels are readable when Surface is raster, or backed by a GPU.
1536
1537The destination pixel storage must be allocated by the caller.
1538
Cary Clark2dc84ad2018-01-26 12:56:22 -05001539Pixel values are converted only if Color_Type and Alpha_Type
Cary Clarka560c472017-11-27 10:44:06 -05001540do not match. Only pixels within both source and destination rectangles
1541are copied. dst contents outside Rect intersection are unchanged.
1542
1543Pass negative values for srcX or srcY to offset pixels across or down destination.
1544
1545Does not copy, and returns false if:
1546
1547#List
1548# Source and destination rectangles do not intersect. ##
1549# Surface pixels could not be converted to dst.colorType() or dst.alphaType(). ##
1550# dst pixels could not be allocated. ##
1551# dst.rowBytes() is too small to contain one row of pixels. ##
1552##
1553
1554#Param dst storage for pixels copied from Surface ##
1555#Param srcX offset into readable pixels in x; may be negative ##
1556#Param srcY offset into readable pixels in y; may be negative ##
1557
1558#Return true if pixels were copied ##
1559
1560#Example
Cary Clark3cd22cc2017-12-01 11:49:58 -05001561 sk_sp<SkSurface> surf(SkSurface::MakeRasterN32Premul(64, 64));
1562 auto surfCanvas = surf->getCanvas();
1563 surfCanvas->clear(SK_ColorGREEN);
1564 SkPaint paint;
1565 surfCanvas->drawOval({2, 10, 58, 54}, paint);
1566 SkImageInfo info = SkImageInfo::Make(64, 64, kBGRA_8888_SkColorType, kPremul_SkAlphaType);
1567 SkBitmap bitmap;
1568 bitmap.setInfo(info);
1569 bitmap.allocPixels();
1570 for (int x : { 32, -32 } ) {
1571 for (int y : { 32, -32 } ) {
1572 surf->readPixels(bitmap, x, y);
1573 }
1574 }
1575 canvas->drawBitmap(bitmap, 0, 0);
Cary Clarka560c472017-11-27 10:44:06 -05001576##
1577
Mike Reed4c790bd2018-02-08 14:10:40 -05001578#SeeAlso peekPixels writePixels
1579
1580#Method ##
1581
1582# ------------------------------------------------------------------------------
1583
1584#Method void writePixels(const SkPixmap& src, int dstX, int dstY)
Cary Clark56356312018-02-08 14:45:18 -05001585#In Pixels
1586#Line # copies Rect of pixels ##
Mike Reed4c790bd2018-02-08 14:10:40 -05001587Copies Rect of pixels from the src Pixmap to the Surface.
1588
1589Source Rect corners are (0, 0) and (src.width(), src.height()).
Cary Clark56356312018-02-08 14:45:18 -05001590Destination Rect corners are (dstX, dstY) and
1591#Formula
1592(dstX + Surface width(), dstY + Surface height())
1593##
1594.
Mike Reed4c790bd2018-02-08 14:10:40 -05001595Copies each readable pixel intersecting both rectangles, without scaling,
1596converting to Surface colorType() and Surface alphaType() if required.
1597
1598#Param src storage for pixels to copy to Surface ##
1599#Param dstX x position relative to Surface to begin copy; may be negative ##
1600#Param dstY x position relative to Surface to begin copy; may be negative ##
1601
1602#Example
Cary Clark56356312018-02-08 14:45:18 -05001603 // incomplete
Mike Reed4c790bd2018-02-08 14:10:40 -05001604##
1605
1606#SeeAlso readPixels peekPixels
1607
1608#Method ##
1609
1610# ------------------------------------------------------------------------------
1611
1612#Method void writePixels(const SkBitmap& src, int dstX, int dstY)
1613
1614Copies Rect of pixels from the src Bitmap to the Surface.
1615
1616Source Rect corners are (0, 0) and (src.width(), src.height()).
Cary Clark56356312018-02-08 14:45:18 -05001617Destination Rect corners are (dstX, dstY) and
1618#Formula
1619(dstX + Surface width(), dstY + Surface height())
1620##
1621.
Mike Reed4c790bd2018-02-08 14:10:40 -05001622Copies each readable pixel intersecting both rectangles, without scaling,
1623converting to Surface colorType() and Surface alphaType() if required.
1624
1625#Param src storage for pixels to copy to Surface ##
1626#Param dstX x position relative to Surface to begin copy; may be negative ##
1627#Param dstY x position relative to Surface to begin copy; may be negative ##
1628
1629#Example
Cary Clark56356312018-02-08 14:45:18 -05001630 // incomplete
Mike Reed4c790bd2018-02-08 14:10:40 -05001631##
1632
1633#SeeAlso readPixels peekPixels
Cary Clarka560c472017-11-27 10:44:06 -05001634
1635#Method ##
1636
1637# ------------------------------------------------------------------------------
1638
1639#Method const SkSurfaceProps& props() const
Cary Clark4855f782018-02-06 09:41:53 -05001640#In Property
Cary Clarkab2621d2018-01-30 10:08:57 -05001641#Line # returns Surface_Properties ##
Cary Clarka560c472017-11-27 10:44:06 -05001642Returns Surface_Properties for surface.
1643
1644#Return LCD striping orientation and setting for device independent fonts ##
1645
1646#Example
1647 const char* names[] = { "Unknown", "RGB_H", "BGR_H", "RGB_V", "BGR_V" };
Cary Clark3cd22cc2017-12-01 11:49:58 -05001648 sk_sp<SkSurface> surf(SkSurface::MakeRasterN32Premul(64, 64));
Cary Clarka560c472017-11-27 10:44:06 -05001649 SkDebugf("surf.props(): k%s_SkPixelGeometry\n", names[surf->props().pixelGeometry()]);
1650#StdOut
1651surf.props(): kRGB_H_SkPixelGeometry
1652##
1653##
1654
1655#SeeAlso SkSurfaceProps
1656
1657#Method ##
1658
1659# ------------------------------------------------------------------------------
1660
1661#Method void prepareForExternalIO()
Cary Clark4855f782018-02-06 09:41:53 -05001662#Deprecated soon
Cary Clarka560c472017-11-27 10:44:06 -05001663#Method ##
1664
1665# ------------------------------------------------------------------------------
Cary Clark4855f782018-02-06 09:41:53 -05001666#Subtopic Utility
1667#Populate
1668#Line # rarely called management functions ##
1669##
Cary Clarka560c472017-11-27 10:44:06 -05001670
1671#Method void flush()
Cary Clark4855f782018-02-06 09:41:53 -05001672#In Utility
Cary Clarkab2621d2018-01-30 10:08:57 -05001673#Line # resolve pending I/O ##
Cary Clarka560c472017-11-27 10:44:06 -05001674Issues pending Surface commands to the GPU-backed API and resolves any Surface MSAA.
1675
1676Skia flushes as needed, so it is not necessary to call this if Skia manages
1677drawing and object lifetime. Call when interleaving Skia calls with native
1678GPU calls.
1679
1680#NoExample
1681##
1682
1683#SeeAlso GrBackendSemaphore
1684
1685#Method ##
1686
1687# ------------------------------------------------------------------------------
1688
1689#Method GrSemaphoresSubmitted flushAndSignalSemaphores(int numSemaphores,
1690 GrBackendSemaphore signalSemaphores[])
Cary Clark4855f782018-02-06 09:41:53 -05001691#In Utility
Cary Clarkab2621d2018-01-30 10:08:57 -05001692#Line # resolve pending I/O, and signal ##
Cary Clarka560c472017-11-27 10:44:06 -05001693
1694Issues pending Surface commands to the GPU-backed API and resolves any Surface MSAA.
1695After issuing all commands, signalSemaphores of count numSemaphores semaphores
1696are signaled by the GPU.
1697
1698For each GrBackendSemaphore in signalSemaphores:
1699if GrBackendSemaphore is initialized, the GPU back-end uses the semaphore as is;
1700otherwise, a new semaphore is created and initializes GrBackendSemaphore.
1701
1702The caller must delete the semaphores created and returned in signalSemaphores.
1703GrBackendSemaphore can be deleted as soon as this function returns.
1704
Cary Clark2a8c48b2018-02-15 17:31:24 -05001705If the back-end API is OpenGL only uninitialized Backend_Semaphores are supported.
Cary Clarka560c472017-11-27 10:44:06 -05001706
1707If the back-end API is Vulkan semaphores may be initialized or uninitialized.
1708If uninitialized, created semaphores are valid only with the VkDevice
1709with which they were created.
1710
1711If GrSemaphoresSubmitted::kNo is returned, the GPU back-end did not create or
1712add any semaphores to signal on the GPU; the caller should not instruct the GPU
1713to wait on any of the semaphores.
1714
1715Pending surface commands are flushed regardless of the return result.
1716
1717#Param numSemaphores size of signalSemaphores array ##
1718#Param signalSemaphores array of semaphore containers ##
1719
1720#Return one of: GrSemaphoresSubmitted::kYes, GrSemaphoresSubmitted::kNo ##
1721
1722#NoExample
1723##
1724
1725#SeeAlso wait GrBackendSemaphore
1726
1727#Method ##
1728
1729# ------------------------------------------------------------------------------
1730
1731#Method bool wait(int numSemaphores, const GrBackendSemaphore* waitSemaphores)
Cary Clark4855f782018-02-06 09:41:53 -05001732#In Utility
Cary Clarkab2621d2018-01-30 10:08:57 -05001733#Line # rause commands until signaled ##
Cary Clarka560c472017-11-27 10:44:06 -05001734Inserts a list of GPU semaphores that the current GPU-backed API must wait on before
1735executing any more commands on the GPU for this surface. Skia will take ownership of the
1736underlying semaphores and delete them once they have been signaled and waited on.
1737If this call returns false, then the GPU back-end will not wait on any passed in semaphores,
1738and the client will still own the semaphores.
1739
1740#Param numSemaphores size of waitSemaphores array ##
1741#Param waitSemaphores array of semaphore containers ##
1742
1743#Return true if GPU is waiting on semaphores ##
1744
1745#Example
1746#ToDo this is copy and paste silliness masquerading as an example. Probably need gpu
1747 globals and definitely need gpu expertise to make a real example out of this
1748 ##
1749#Platform !fiddle gpu
1750#Height 64
Cary Clark3cd22cc2017-12-01 11:49:58 -05001751 SkPaint paint;
1752 paint.setTextSize(32);
1753 GrContext* context = canvas->getGrContext();
1754 if (!context) {
1755 canvas->drawString("GPU only!", 20, 40, paint);
1756 return;
1757 }
Cary Clarka560c472017-11-27 10:44:06 -05001758 GrBackendSemaphore semaphore;
Cary Clark3cd22cc2017-12-01 11:49:58 -05001759 sk_sp<SkSurface> surface = SkSurface::MakeRenderTarget(
1760 context, SkBudgeted::kYes, SkImageInfo::MakeN32Premul(64, 64));
Cary Clarka560c472017-11-27 10:44:06 -05001761 surface->flushAndSignalSemaphores(1, &semaphore);
1762 sk_sp<SkImage> image = surface->makeImageSnapshot();
1763 GrBackendObject backendImage = image->getTextureHandle(false); // unused
1764 SkASSERT(backendImage);
1765 const SkImageInfo childImageInfo = SkImageInfo::Make(64, 64,
1766 kRGBA_8888_SkColorType, kPremul_SkAlphaType);
1767 sk_sp<SkSurface> childSurface(SkSurface::MakeRenderTarget(context, SkBudgeted::kNo,
1768 childImageInfo, 0, kTopLeft_GrSurfaceOrigin, nullptr));
1769 GrBackendTexture backendTexture;
1770 sk_sp<SkImage> childImage = SkImage::MakeFromTexture(context,
1771 backendTexture, // undefined
1772 kTopLeft_GrSurfaceOrigin, kPremul_SkAlphaType, nullptr);
1773 SkCanvas* childCanvas = childSurface->getCanvas();
1774 childCanvas->clear(SK_ColorRED);
1775 childSurface->wait(1, &semaphore);
1776 childCanvas->drawImage(childImage, 32, 0);
Cary Clark3cd22cc2017-12-01 11:49:58 -05001777 childSurface->draw(canvas, 0, 0, nullptr);
Cary Clarka560c472017-11-27 10:44:06 -05001778##
1779
1780#SeeAlso flushAndSignalSemaphores GrBackendSemaphore
1781
1782#Method ##
1783
1784# ------------------------------------------------------------------------------
1785
1786#Method bool characterize(SkSurfaceCharacterization* characterization) const
Cary Clark4855f782018-02-06 09:41:53 -05001787#In Utility
1788#Line # sets Surface_Characterization for threaded GPU processing ##
Cary Clarka560c472017-11-27 10:44:06 -05001789Initializes Surface_Characterization that can be used to perform GPU back-end
Cary Clark4855f782018-02-06 09:41:53 -05001790processing in a separate thread. Typically this is used to divide drawing
Cary Clarka560c472017-11-27 10:44:06 -05001791into multiple tiles. DeferredDisplayListRecorder records the drawing commands
1792for each tile.
1793
1794Return true if Surface supports characterization. Raster_Surface returns false.
1795
1796#Param characterization properties for parallel drawing ##
1797
1798#Return true if supported ##
1799
1800#Example
1801#Platform gpu
1802#Height 64
Cary Clark3cd22cc2017-12-01 11:49:58 -05001803 SkPaint paint;
1804 paint.setTextSize(32);
1805 GrContext* context = canvas->getGrContext();
1806 if (!context) {
1807 canvas->drawString("GPU only!", 20, 40, paint);
1808 return;
1809 }
1810 sk_sp<SkSurface> gpuSurface = SkSurface::MakeRenderTarget(
1811 context, SkBudgeted::kYes, SkImageInfo::MakeN32Premul(64, 64));
1812 SkSurfaceCharacterization characterization;
1813 if (!gpuSurface->characterize(&characterization)) {
1814 canvas->drawString("characterization unsupported", 20, 40, paint);
1815 return;
1816 }
1817 // start of threadable work
1818 SkDeferredDisplayListRecorder recorder(characterization);
1819 SkCanvas* subCanvas = recorder.getCanvas();
1820 subCanvas->clear(SK_ColorGREEN);
1821 std::unique_ptr<SkDeferredDisplayList> displayList = recorder.detach();
1822 // end of threadable work
1823 gpuSurface->draw(displayList.get());
1824 sk_sp<SkImage> img = gpuSurface->makeImageSnapshot();
1825 canvas->drawImage(std::move(img), 0, 0);
Cary Clarka560c472017-11-27 10:44:06 -05001826##
1827
1828#SeeAlso draw() SkSurfaceCharacterization SkDeferredDisplayList
1829
1830#Method ##
1831
1832# ------------------------------------------------------------------------------
1833
Cary Clark2f466242017-12-11 16:03:17 -05001834#Method bool draw(SkDeferredDisplayList* deferredDisplayList)
Cary Clarka560c472017-11-27 10:44:06 -05001835
1836Draws deferred display list created using SkDeferredDisplayListRecorder.
Cary Clark2f466242017-12-11 16:03:17 -05001837Has no effect and returns false if Surface_Characterization stored in
1838deferredDisplayList is not compatible with Surface.
1839
1840Raster_Surface returns false.
Cary Clarka560c472017-11-27 10:44:06 -05001841
1842#Param deferredDisplayList drawing commands ##
1843
Cary Clark2f466242017-12-11 16:03:17 -05001844#Return false if deferredDisplayList is not compatible ##
1845
Cary Clarka560c472017-11-27 10:44:06 -05001846#Example
1847#Height 64
1848#Platform gpu cpu
Cary Clark3cd22cc2017-12-01 11:49:58 -05001849 SkPaint paint;
1850 paint.setTextSize(16);
1851 sk_sp<SkSurface> gpuSurface = SkSurface::MakeRasterN32Premul(64, 64);
1852 SkSurfaceCharacterization characterization;
1853 if (!gpuSurface->characterize(&characterization)) {
1854 canvas->drawString("characterization unsupported", 20, 40, paint);
1855 return;
1856 }
1857 // start of threadable work
1858 SkDeferredDisplayListRecorder recorder(characterization);
1859 SkCanvas* subCanvas = recorder.getCanvas();
1860 subCanvas->clear(SK_ColorGREEN);
1861 std::unique_ptr<SkDeferredDisplayList> displayList = recorder.detach();
1862 // end of threadable work
1863 gpuSurface->draw(displayList.get());
1864 sk_sp<SkImage> img = gpuSurface->makeImageSnapshot();
1865 canvas->drawImage(std::move(img), 0, 0);
Cary Clarka560c472017-11-27 10:44:06 -05001866##
1867
1868#SeeAlso characterize() SkSurfaceCharacterization SkDeferredDisplayList
1869
1870#Method ##
1871
1872#Class SkSurface ##
1873
1874#Topic Surface ##