blob: 4f2549b03a79a3463fd97b322801f1094bbeb53f [file] [log] [blame]
Cary Clarka560c472017-11-27 10:44:06 -05001#Topic Image
2#Alias Image_Reference
3
4#Class SkImage
5
Cary Clark61ca7c52018-01-02 11:34:14 -05006Image describes a two dimensional array of pixels to draw. The pixels may be
Cary Clark4855f782018-02-06 09:41:53 -05007decoded in a Raster_Bitmap, encoded in a Picture or compressed data stream,
Cary Clark61ca7c52018-01-02 11:34:14 -05008or located in GPU memory as a GPU_Texture.
9
10Image cannot be modified after it is created. Image may allocate additional
11storage as needed; for instance, an encoded Image may decode when drawn.
12
13Image width and height are greater than zero. Creating an Image with zero width
14or height returns Image equal to nullptr.
15
16Image may be created from Bitmap, Pixmap, Surface, Picture, encoded streams,
17GPU_Texture, YUV_ColorSpace data, or hardware buffer. Encoded streams supported
Cary Clark4855f782018-02-06 09:41:53 -050018include BMP, GIF, HEIF, ICO, JPEG, PNG, WBMP, WebP. Supported encoding details
Cary Clark61ca7c52018-01-02 11:34:14 -050019vary with platform.
20
Cary Clark08895c42018-02-01 09:37:32 -050021#Subtopic Raster_Image
Cary Clark61ca7c52018-01-02 11:34:14 -050022#Alias Raster_Image
Cary Clark4855f782018-02-06 09:41:53 -050023#Line # pixels decoded in Raster_Bitmap ##
24Raster_Image pixels are decoded in a Raster_Bitmap. These pixels may be read
Cary Clark61ca7c52018-01-02 11:34:14 -050025directly and in most cases written to, although edited pixels may not be drawn
26if Image has been copied internally.
27##
28
Cary Clark08895c42018-02-01 09:37:32 -050029#Subtopic Texture_Image
30#Line # pixels located on GPU ##
Cary Clark61ca7c52018-01-02 11:34:14 -050031Texture_Image are located on GPU and pixels are not accessible. Texture_Image
32are allocated optimally for best performance. Raster_Image may
33be drawn to GPU_Surface, but pixels are uploaded from CPU to GPU downgrading
34performance.
35##
36
Cary Clark08895c42018-02-01 09:37:32 -050037#Subtopic Lazy_Image
38#Line # deferred pixel buffer ##
Cary Clark61ca7c52018-01-02 11:34:14 -050039Lazy_Image defer allocating buffer for Image pixels and decoding stream until
40Image is drawn. Lazy_Image caches result if possible to speed up repeated
41drawing.
42##
Cary Clarka560c472017-11-27 10:44:06 -050043
Cary Clark682c58d2018-05-16 07:07:07 -040044#Subtopic Overview
Cary Clark08895c42018-02-01 09:37:32 -050045#Populate
46##
Cary Clarka560c472017-11-27 10:44:06 -050047
Cary Clark682c58d2018-05-16 07:07:07 -040048#Subtopic Related_Function
Cary Clark08895c42018-02-01 09:37:32 -050049#Populate
Cary Clarka560c472017-11-27 10:44:06 -050050##
51
Cary Clark4855f782018-02-06 09:41:53 -050052#Subtopic Constructor
Cary Clark08895c42018-02-01 09:37:32 -050053#Populate
54##
Cary Clark5081eed2018-01-22 07:55:48 -050055
Cary Clark4855f782018-02-06 09:41:53 -050056#Subtopic Member_Function
Cary Clark08895c42018-02-01 09:37:32 -050057#Populate
58##
Cary Clarka560c472017-11-27 10:44:06 -050059
Cary Clarka560c472017-11-27 10:44:06 -050060# ------------------------------------------------------------------------------
61
62#Method static sk_sp<SkImage> MakeRasterCopy(const SkPixmap& pixmap)
Cary Clark4855f782018-02-06 09:41:53 -050063#In Constructor
64#Line # creates Image from Pixmap and copied pixels ##
Cary Clark2f466242017-12-11 16:03:17 -050065Creates Image from Pixmap and copy of pixels. Since pixels are copied, Pixmap
66pixels may be modified or deleted without affecting Image.
Cary Clarka560c472017-11-27 10:44:06 -050067
Cary Clark3cd22cc2017-12-01 11:49:58 -050068Image is returned if Pixmap is valid. Valid Pixmap parameters include:
69dimensions are greater than zero;
70each dimension fits in 29 bits;
71Color_Type and Alpha_Type are valid, and Color_Type is not kUnknown_SkColorType;
72row bytes are large enough to hold one row of pixels;
73pixel address is not nullptr.
74
75#Param pixmap Image_Info, pixel address, and row bytes ##
76
77#Return copy of Pixmap pixels, or nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -050078
79#Example
Cary Clark2f466242017-12-11 16:03:17 -050080#Height 50
81#Description
82Draw a five by five bitmap, and draw a copy in an Image. Editing the pixmap
83alters the bitmap draw, but does not alter the Image draw since the Image
84contains a copy of the pixels.
85##
86 uint8_t storage[][5] = {{ 0xCA, 0xDA, 0xCA, 0xC9, 0xA3 },
87 { 0xAC, 0xA8, 0x89, 0xA7, 0x87 },
88 { 0x9B, 0xB5, 0xE5, 0x95, 0x46 },
89 { 0x90, 0x81, 0xC5, 0x71, 0x33 },
90 { 0x75, 0x55, 0x44, 0x40, 0x30 }};
91 SkImageInfo imageInfo = SkImageInfo::Make(5, 5, kGray_8_SkColorType, kOpaque_SkAlphaType);
92 SkPixmap pixmap(imageInfo, storage[0], sizeof(storage) / 5);
93 SkBitmap bitmap;
94 bitmap.installPixels(pixmap);
95 sk_sp<SkImage> image = SkImage::MakeRasterCopy(pixmap);
96 *pixmap.writable_addr8(2, 2) = 0x00;
97 canvas->scale(10, 10);
98 canvas->drawBitmap(bitmap, 0, 0);
99 canvas->drawImage(image, 10, 0);
Cary Clarka560c472017-11-27 10:44:06 -0500100##
101
Cary Clark3cd22cc2017-12-01 11:49:58 -0500102#SeeAlso MakeRasterData MakeFromGenerator
Cary Clarka560c472017-11-27 10:44:06 -0500103
104#Method ##
105
106# ------------------------------------------------------------------------------
107
Cary Clarkcc45cc72018-05-15 16:06:12 -0400108#Method static sk_sp<SkImage> MakeRasterData(const SkImageInfo& info, sk_sp<SkData> pixels, size_t rowBytes)
Cary Clark4855f782018-02-06 09:41:53 -0500109#In Constructor
110#Line # creates Image from Image_Info and shared pixels ##
Cary Clark3cd22cc2017-12-01 11:49:58 -0500111Creates Image from Image_Info, sharing pixels.
Cary Clarka560c472017-11-27 10:44:06 -0500112
Cary Clark3cd22cc2017-12-01 11:49:58 -0500113Image is returned if Image_Info is valid. Valid Image_Info parameters include:
114dimensions are greater than zero;
115each dimension fits in 29 bits;
116Color_Type and Alpha_Type are valid, and Color_Type is not kUnknown_SkColorType;
117rowBytes are large enough to hold one row of pixels;
118pixels is not nullptr, and contains enough data for Image.
119
120#Param info contains width, height, Alpha_Type, Color_Type, Color_Space ##
121#Param pixels address or pixel storage ##
122#Param rowBytes size of pixel row or larger ##
123
124#Return Image sharing pixels, or nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -0500125
126#Example
Cary Clark0c5f5462017-12-15 11:21:51 -0500127#Image 3
128 size_t rowBytes = image->width() * SkColorTypeBytesPerPixel(kRGBA_8888_SkColorType);
129 sk_sp<SkData> data = SkData::MakeUninitialized(rowBytes * image->height());
Cary Clark682c58d2018-05-16 07:07:07 -0400130 SkImageInfo dstInfo = SkImageInfo::MakeN32(image->width(), image->height(),
Cary Clark0c5f5462017-12-15 11:21:51 -0500131 kPremul_SkAlphaType);
132 image->readPixels(dstInfo, data->writable_data(), rowBytes, 0, 0, SkImage::kAllow_CachingHint);
133 sk_sp<SkImage> raw = SkImage::MakeRasterData(dstInfo.makeColorType(kRGBA_8888_SkColorType),
134 data, rowBytes);
135 canvas->drawImage(image, 0, 0);
136 canvas->drawImage(raw.get(), 128, 0);
Cary Clarka560c472017-11-27 10:44:06 -0500137##
138
Cary Clark3cd22cc2017-12-01 11:49:58 -0500139#SeeAlso MakeRasterCopy MakeFromGenerator
Cary Clarka560c472017-11-27 10:44:06 -0500140
141#Method ##
142
143# ------------------------------------------------------------------------------
144
Cary Clark3cd22cc2017-12-01 11:49:58 -0500145#Typedef void* ReleaseContext
Cary Clark682c58d2018-05-16 07:07:07 -0400146#Line # parameter type for MakeFromRaster ##
Cary Clarkffb3d682018-05-17 12:17:28 -0400147
148#Code
149typedef void* ReleaseContext;
150##
151
Cary Clark3cd22cc2017-12-01 11:49:58 -0500152Caller data passed to RasterReleaseProc; may be nullptr.
153
154#SeeAlso MakeFromRaster RasterReleaseProc
155
156##
157
Cary Clarka560c472017-11-27 10:44:06 -0500158#Typedef void (*RasterReleaseProc)(const void* pixels, ReleaseContext)
Cary Clark682c58d2018-05-16 07:07:07 -0400159#Line # parameter type for MakeFromRaster ##
Cary Clarkffb3d682018-05-17 12:17:28 -0400160
161#Code
162typedef void (*RasterReleaseProc)(const void* pixels, ReleaseContext);
163##
164
Cary Clark3cd22cc2017-12-01 11:49:58 -0500165Function called when Image no longer shares pixels. ReleaseContext is
Cary Clark682c58d2018-05-16 07:07:07 -0400166provided by caller when Image is created, and may be nullptr.
Cary Clark3cd22cc2017-12-01 11:49:58 -0500167
168#SeeAlso ReleaseContext MakeFromRaster
169
Cary Clarka560c472017-11-27 10:44:06 -0500170##
171
172#Method static sk_sp<SkImage> MakeFromRaster(const SkPixmap& pixmap,
173 RasterReleaseProc rasterReleaseProc,
174 ReleaseContext releaseContext)
Cary Clark4855f782018-02-06 09:41:53 -0500175#In Constructor
176#Line # creates Image from Pixmap, with release ##
Cary Clarka560c472017-11-27 10:44:06 -0500177
Cary Clark0c5f5462017-12-15 11:21:51 -0500178Creates Image from pixmap, sharing Pixmap pixels. Pixels must remain valid and
Cary Clark3cd22cc2017-12-01 11:49:58 -0500179unchanged until rasterReleaseProc is called. rasterReleaseProc is passed
180releaseContext when Image is deleted or no longer refers to pixmap pixels.
Cary Clarka560c472017-11-27 10:44:06 -0500181
Cary Clark0c5f5462017-12-15 11:21:51 -0500182Pass nullptr for rasterReleaseProc to share Pixmap without requiring a callback
183when Image is released. Pass nullptr for releaseContext if rasterReleaseProc
184does not require state.
185
Cary Clark3cd22cc2017-12-01 11:49:58 -0500186Image is returned if pixmap is valid. Valid Pixmap parameters include:
187dimensions are greater than zero;
188each dimension fits in 29 bits;
189Color_Type and Alpha_Type are valid, and Color_Type is not kUnknown_SkColorType;
190row bytes are large enough to hold one row of pixels;
191pixel address is not nullptr.
192
193#Param pixmap Image_Info, pixel address, and row bytes ##
Cary Clark0c5f5462017-12-15 11:21:51 -0500194#Param rasterReleaseProc function called when pixels can be released; or nullptr ##
195#Param releaseContext state passed to rasterReleaseProc; or nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -0500196
Cary Clark0c5f5462017-12-15 11:21:51 -0500197#Return Image sharing pixmap ##
Cary Clarka560c472017-11-27 10:44:06 -0500198
199#Example
Cary Clark0c5f5462017-12-15 11:21:51 -0500200#Function
201static void releaseProc(const void* pixels, SkImage::ReleaseContext context) {
202 int* countPtr = static_cast<int*>(context);
203 *countPtr += 1;
204}
205##
206
207void draw(SkCanvas* canvas) {
208 SkColor color = 0;
209 SkPixmap pixmap(SkImageInfo::MakeN32(1, 1, kPremul_SkAlphaType), &color, 4);
210 int releaseCount = 0;
211 sk_sp<SkImage> image(SkImage::MakeFromRaster(pixmap, releaseProc, &releaseCount));
212 SkDebugf("before reset: %d\n", releaseCount);
213 image.reset();
214 SkDebugf("after reset: %d\n", releaseCount);
215}
216#StdOut
217before reset: 0
218after reset: 1
219##
Cary Clarka560c472017-11-27 10:44:06 -0500220##
221
Cary Clark3cd22cc2017-12-01 11:49:58 -0500222#SeeAlso MakeRasterCopy MakeRasterData MakeFromGenerator RasterReleaseProc ReleaseContext
Cary Clarka560c472017-11-27 10:44:06 -0500223
224#Method ##
225
226# ------------------------------------------------------------------------------
227
228#Method static sk_sp<SkImage> MakeFromBitmap(const SkBitmap& bitmap)
Cary Clark4855f782018-02-06 09:41:53 -0500229#In Constructor
230#Line # creates Image from Bitmap, sharing or copying pixels ##
Cary Clark682c58d2018-05-16 07:07:07 -0400231Creates Image from bitmap, sharing or copying bitmap pixels. If the bitmap
Cary Clark3cd22cc2017-12-01 11:49:58 -0500232is marked immutable, and its pixel memory is shareable, it may be shared
233instead of copied.
Cary Clarka560c472017-11-27 10:44:06 -0500234
Cary Clark3cd22cc2017-12-01 11:49:58 -0500235Image is returned if bitmap is valid. Valid Bitmap parameters include:
236dimensions are greater than zero;
237each dimension fits in 29 bits;
238Color_Type and Alpha_Type are valid, and Color_Type is not kUnknown_SkColorType;
239row bytes are large enough to hold one row of pixels;
240pixel address is not nullptr.
Cary Clarka560c472017-11-27 10:44:06 -0500241
Cary Clark3cd22cc2017-12-01 11:49:58 -0500242#Param bitmap Image_Info, row bytes, and pixels ##
243
244#Return created Image, or nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -0500245
246#Example
Cary Clark0c5f5462017-12-15 11:21:51 -0500247#Description
248The first Bitmap is shared; writing to the pixel memory changes the first
249Image.
250The second Bitmap is marked immutable, and is copied; writing to the pixel
251memory does not alter the second Image.
252##
253#Height 50
254 uint8_t storage[][5] = {{ 0xCA, 0xDA, 0xCA, 0xC9, 0xA3 },
255 { 0xAC, 0xA8, 0x89, 0xA7, 0x87 },
256 { 0x9B, 0xB5, 0xE5, 0x95, 0x46 },
257 { 0x90, 0x81, 0xC5, 0x71, 0x33 },
258 { 0x75, 0x55, 0x44, 0x40, 0x30 }};
259 SkImageInfo imageInfo = SkImageInfo::Make(5, 5, kGray_8_SkColorType, kOpaque_SkAlphaType);
260 SkPixmap pixmap(imageInfo, storage[0], sizeof(storage) / 5);
261 SkBitmap bitmap;
262 bitmap.installPixels(pixmap);
263 sk_sp<SkImage> image1 = SkImage::MakeFromBitmap(bitmap);
264 bitmap.setImmutable();
265 sk_sp<SkImage> image2 = SkImage::MakeFromBitmap(bitmap);
266 *pixmap.writable_addr8(2, 2) = 0x00;
267 canvas->scale(10, 10);
268 canvas->drawImage(image1, 0, 0);
269 canvas->drawImage(image2, 10, 0);
Cary Clarka560c472017-11-27 10:44:06 -0500270##
271
Cary Clark3cd22cc2017-12-01 11:49:58 -0500272#SeeAlso MakeFromRaster MakeRasterCopy MakeFromGenerator MakeRasterData
Cary Clarka560c472017-11-27 10:44:06 -0500273
274#Method ##
275
276# ------------------------------------------------------------------------------
277
278#Method static sk_sp<SkImage> MakeFromGenerator(std::unique_ptr<SkImageGenerator> imageGenerator,
279 const SkIRect* subset = nullptr)
Cary Clark4855f782018-02-06 09:41:53 -0500280#In Constructor
281#Line # creates Image from a stream of data ##
Cary Clarka560c472017-11-27 10:44:06 -0500282
Cary Clark0c5f5462017-12-15 11:21:51 -0500283Creates Image from data returned by imageGenerator. Generated data is owned by Image and may not
284be shared or accessed.
Cary Clarka560c472017-11-27 10:44:06 -0500285
Cary Clark0c5f5462017-12-15 11:21:51 -0500286subset allows selecting a portion of the full image. Pass nullptr to select the entire image;
287otherwise, subset must be contained by image bounds.
288
289Image is returned if generator data is valid. Valid data parameters vary by type of data
290and platform.
Cary Clarka560c472017-11-27 10:44:06 -0500291
Cary Clark3cd22cc2017-12-01 11:49:58 -0500292imageGenerator may wrap Picture data, codec data, or custom data.
293
294#Param imageGenerator stock or custom routines to retrieve Image ##
295#Param subset bounds of returned Image; may be nullptr ##
296
297#Return created Image, or nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -0500298
299#Example
Cary Clarkac47b882018-01-11 10:35:44 -0500300#Height 128
Cary Clark0c5f5462017-12-15 11:21:51 -0500301#Description
302The generator returning Picture cannot be shared; std::move transfers ownership to generated Image.
303##
304 SkPictureRecorder recorder;
305 recorder.beginRecording(100, 100)->drawColor(SK_ColorRED);
306 auto picture = recorder.finishRecordingAsPicture();
307 auto gen = SkImageGenerator::MakeFromPicture({100, 100}, picture, nullptr, nullptr,
308 SkImage::BitDepth::kU8, SkColorSpace::MakeSRGB());
309 sk_sp<SkImage> image = SkImage::MakeFromGenerator(std::move(gen));
310 canvas->drawImage(image, 0, 0);
Cary Clarka560c472017-11-27 10:44:06 -0500311##
312
Cary Clark3cd22cc2017-12-01 11:49:58 -0500313#SeeAlso MakeFromEncoded
Cary Clarka560c472017-11-27 10:44:06 -0500314
315#Method ##
316
317# ------------------------------------------------------------------------------
318
319#Method static sk_sp<SkImage> MakeFromEncoded(sk_sp<SkData> encoded, const SkIRect* subset = nullptr)
Cary Clark4855f782018-02-06 09:41:53 -0500320#In Constructor
321#Line # creates Image from encoded data ##
Cary Clark682c58d2018-05-16 07:07:07 -0400322Creates Image from encoded data.
Cary Clark0c5f5462017-12-15 11:21:51 -0500323subset allows selecting a portion of the full image. Pass nullptr to select the entire image;
324otherwise, subset must be contained by image bounds.
Cary Clarka560c472017-11-27 10:44:06 -0500325
Cary Clark3cd22cc2017-12-01 11:49:58 -0500326Image is returned if format of the encoded data is recognized and supported.
Cary Clark4855f782018-02-06 09:41:53 -0500327Recognized formats vary by platform.
Cary Clarka560c472017-11-27 10:44:06 -0500328
Cary Clark3cd22cc2017-12-01 11:49:58 -0500329#Param encoded data of Image to decode ##
330#Param subset bounds of returned Image; may be nullptr ##
331
332#Return created Image, or nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -0500333
Cary Clark61ca7c52018-01-02 11:34:14 -0500334#Example
335#Image 3
336int x = 0;
337for (int quality : { 100, 50, 10, 1} ) {
338 sk_sp<SkData> encodedData = image->encodeToData(SkEncodedImageFormat::kJPEG, quality);
339 sk_sp<SkImage> image = SkImage::MakeFromEncoded(encodedData);
340 canvas->drawImage(image, x, 0);
341 x += 64;
342}
Cary Clarka560c472017-11-27 10:44:06 -0500343##
344
Cary Clark3cd22cc2017-12-01 11:49:58 -0500345#SeeAlso MakeFromGenerator
Cary Clarka560c472017-11-27 10:44:06 -0500346
347#Method ##
348
349# ------------------------------------------------------------------------------
350
351#Typedef void (*TextureReleaseProc)(ReleaseContext releaseContext)
Cary Clark682c58d2018-05-16 07:07:07 -0400352#Line # parameter type for MakeFromTexture ##
Cary Clarkffb3d682018-05-17 12:17:28 -0400353
354#Code
355typedef void (*TextureReleaseProc)(ReleaseContext releaseContext);
356##
357
Cary Clark682c58d2018-05-16 07:07:07 -0400358User function called when supplied texture may be deleted.
359#SeeAlso MakeFromTexture
Cary Clarka560c472017-11-27 10:44:06 -0500360##
361
362#Method static sk_sp<SkImage> MakeFromTexture(GrContext* context,
363 const GrBackendTexture& backendTexture,
364 GrSurfaceOrigin origin,
Cary Clark61ca7c52018-01-02 11:34:14 -0500365 SkColorType colorType,
366 SkAlphaType alphaType,
367 sk_sp<SkColorSpace> colorSpace)
Cary Clarkf895a422018-02-27 09:54:21 -0500368#In Constructor
369#Line # creates Image from GPU_Texture ##
Cary Clark61ca7c52018-01-02 11:34:14 -0500370Creates Image from GPU_Texture associated with context. Caller is responsible for
371managing the lifetime of GPU_Texture.
372
373Image is returned if format of backendTexture is recognized and supported.
374Recognized formats vary by GPU back-end.
375
376#Param context GPU_Context ##
377#Param backendTexture texture residing on GPU ##
378#Param origin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin ##
Cary Clark1a8d7622018-03-05 13:26:16 -0500379#Param colorType one of: #list_of_color_types#
Cary Clark61ca7c52018-01-02 11:34:14 -0500380##
Cary Clark681287e2018-03-16 11:34:15 -0400381#Param alphaType one of: #list_of_alpha_types#
Cary Clark61ca7c52018-01-02 11:34:14 -0500382##
383#Param colorSpace range of colors; may be nullptr ##
Cary Clark3cd22cc2017-12-01 11:49:58 -0500384
385#Return created Image, or nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -0500386
387#Example
Cary Clark0c5f5462017-12-15 11:21:51 -0500388#Image 3
389#Platform gpu
390#Height 128
391#Description
392A back-end texture has been created and uploaded to the GPU outside of this example.
393##
394GrContext* context = canvas->getGrContext();
395if (!context) {
396 return;
397}
398canvas->scale(.25f, .25f);
399int x = 0;
400for (auto origin : { kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin } ) {
Cary Clarkac47b882018-01-11 10:35:44 -0500401 sk_sp<SkImage> image = SkImage::MakeFromTexture(context, backEndTexture,
Cary Clark56356312018-02-08 14:45:18 -0500402 origin, kN32_SkColorType, kOpaque_SkAlphaType, nullptr);
Cary Clark0c5f5462017-12-15 11:21:51 -0500403 canvas->drawImage(image, x, 0);
404x += 512;
405}
Cary Clarka560c472017-11-27 10:44:06 -0500406##
407
Cary Clark3cd22cc2017-12-01 11:49:58 -0500408#SeeAlso MakeFromAdoptedTexture SkSurface::MakeFromBackendTexture
Cary Clarka560c472017-11-27 10:44:06 -0500409
410#Method ##
411
412# ------------------------------------------------------------------------------
413
414#Method static sk_sp<SkImage> MakeFromTexture(GrContext* context,
415 const GrBackendTexture& backendTexture,
416 GrSurfaceOrigin origin,
Cary Clark61ca7c52018-01-02 11:34:14 -0500417 SkColorType colorType,
Cary Clarka560c472017-11-27 10:44:06 -0500418 SkAlphaType alphaType,
419 sk_sp<SkColorSpace> colorSpace,
420 TextureReleaseProc textureReleaseProc,
421 ReleaseContext releaseContext)
422
Cary Clark61ca7c52018-01-02 11:34:14 -0500423Creates Image from GPU_Texture associated with context. GPU_Texture must stay
Cary Clark3cd22cc2017-12-01 11:49:58 -0500424valid and unchanged until textureReleaseProc is called. textureReleaseProc is
425passed releaseContext when Image is deleted or no longer refers to texture.
Cary Clarka560c472017-11-27 10:44:06 -0500426
Cary Clark3cd22cc2017-12-01 11:49:58 -0500427Image is returned if format of backendTexture is recognized and supported.
428Recognized formats vary by GPU back-end.
Cary Clarka560c472017-11-27 10:44:06 -0500429
Cary Clark3cd22cc2017-12-01 11:49:58 -0500430#Param context GPU_Context ##
431#Param backendTexture texture residing on GPU ##
432#Param origin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin ##
Cary Clark1a8d7622018-03-05 13:26:16 -0500433#Param colorType one of: #list_of_color_types#
Cary Clark61ca7c52018-01-02 11:34:14 -0500434##
Cary Clark681287e2018-03-16 11:34:15 -0400435#Param alphaType one of: #list_of_alpha_types#
Cary Clark3cd22cc2017-12-01 11:49:58 -0500436##
Cary Clark61ca7c52018-01-02 11:34:14 -0500437#Param colorSpace range of colors; may be nullptr ##
Cary Clark3cd22cc2017-12-01 11:49:58 -0500438#Param textureReleaseProc function called when texture can be released ##
439#Param releaseContext state passed to textureReleaseProc ##
440
441#Return created Image, or nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -0500442
Cary Clark0c5f5462017-12-15 11:21:51 -0500443#ToDo
444This doesn't do anything clever with TextureReleaseProc because it may not get called
Cary Clark61ca7c52018-01-02 11:34:14 -0500445fwithin the lifetime of the example
Cary Clark0c5f5462017-12-15 11:21:51 -0500446##
447
Cary Clarka560c472017-11-27 10:44:06 -0500448#Example
Cary Clarkac47b882018-01-11 10:35:44 -0500449#Platform gpu
450#Image 4
Cary Clark0c5f5462017-12-15 11:21:51 -0500451GrContext* context = canvas->getGrContext();
452if (!context) {
453 return;
454}
Cary Clarkac47b882018-01-11 10:35:44 -0500455auto debugster = [](SkImage::ReleaseContext releaseContext) -> void {
456 *((int *) releaseContext) += 128;
Cary Clark0c5f5462017-12-15 11:21:51 -0500457};
458int x = 0;
459for (auto origin : { kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin } ) {
Cary Clarkac47b882018-01-11 10:35:44 -0500460 sk_sp<SkImage> image = SkImage::MakeFromTexture(context, backEndTexture,
Cary Clark61ca7c52018-01-02 11:34:14 -0500461 origin, kRGBA_8888_SkColorType, kOpaque_SkAlphaType, nullptr, debugster, &x);
Cary Clark0c5f5462017-12-15 11:21:51 -0500462 canvas->drawImage(image, x, 0);
463 x += 128;
464}
Cary Clarka560c472017-11-27 10:44:06 -0500465##
466
Cary Clark3cd22cc2017-12-01 11:49:58 -0500467#SeeAlso MakeFromAdoptedTexture SkSurface::MakeFromBackendTexture
Cary Clarka560c472017-11-27 10:44:06 -0500468
469#Method ##
470
471# ------------------------------------------------------------------------------
472
473#Method static sk_sp<SkImage> MakeCrossContextFromEncoded(GrContext* context, sk_sp<SkData> data,
474 bool buildMips,
Brian Osman584b5012018-04-13 15:48:26 -0400475 SkColorSpace* dstColorSpace,
476 bool limitToMaxTextureSize = false)
Cary Clark4855f782018-02-06 09:41:53 -0500477#In Constructor
478#Line # creates Image from encoded data, and uploads to GPU ##
Cary Clarka560c472017-11-27 10:44:06 -0500479
Cary Clark682c58d2018-05-16 07:07:07 -0400480Creates Image from encoded data. Image is uploaded to GPU back-end using context.
Cary Clark3cd22cc2017-12-01 11:49:58 -0500481
482Created Image is available to other GPU contexts, and is available across thread
Cary Clark682c58d2018-05-16 07:07:07 -0400483boundaries. All contexts must be in the same GPU_Share_Group, or otherwise
Cary Clark3cd22cc2017-12-01 11:49:58 -0500484share resources.
485
486When Image is no longer referenced, context releases texture memory
Cary Clarka560c472017-11-27 10:44:06 -0500487asynchronously.
Cary Clarka560c472017-11-27 10:44:06 -0500488
Cary Clark3cd22cc2017-12-01 11:49:58 -0500489Texture decoded from data is uploaded to match Surface created with
490dstColorSpace. Color_Space of Image is determined by encoded data.
Cary Clarka560c472017-11-27 10:44:06 -0500491
Cary Clark3cd22cc2017-12-01 11:49:58 -0500492Image is returned if format of data is recognized and supported, and if context
493supports moving resources. Recognized formats vary by platform and GPU back-end.
494
Cary Clark61ca7c52018-01-02 11:34:14 -0500495Image is returned using MakeFromEncoded if context is nullptr or does not support
496moving resources between contexts.
497
Cary Clark3cd22cc2017-12-01 11:49:58 -0500498#Param context GPU_Context ##
499#Param data Image to decode ##
500#Param buildMips create Image as Mip_Map if true ##
501#Param dstColorSpace range of colors of matching Surface on GPU ##
Brian Osman584b5012018-04-13 15:48:26 -0400502#Param limitToMaxTextureSize downscale image to GPU maximum texture size, if necessary ##
Cary Clark3cd22cc2017-12-01 11:49:58 -0500503
504#Return created Image, or nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -0500505
506#Example
Cary Clark61ca7c52018-01-02 11:34:14 -0500507#Image 4
Cary Clarkac47b882018-01-11 10:35:44 -0500508#Height 64
Cary Clark61ca7c52018-01-02 11:34:14 -0500509GrContext* context = canvas->getGrContext();
510sk_sp<SkData> encodedData = image->encodeToData(SkEncodedImageFormat::kJPEG, 100);
511sk_sp<SkImage> image = SkImage::MakeCrossContextFromEncoded(context,
512 encodedData, false, nullptr);
513canvas->drawImage(image, 0, 0);
Cary Clarka560c472017-11-27 10:44:06 -0500514##
515
Cary Clark3cd22cc2017-12-01 11:49:58 -0500516#SeeAlso MakeCrossContextFromPixmap
517
518#Method ##
519
520# ------------------------------------------------------------------------------
521
522#Method static sk_sp<SkImage> MakeCrossContextFromPixmap(GrContext* context, const SkPixmap& pixmap,
523 bool buildMips,
Brian Osman584b5012018-04-13 15:48:26 -0400524 SkColorSpace* dstColorSpace,
525 bool limitToMaxTextureSize = false)
Cary Clark4855f782018-02-06 09:41:53 -0500526#In Constructor
527#Line # creates Image from Pixmap, and uploads to GPU ##
Cary Clark3cd22cc2017-12-01 11:49:58 -0500528
Cary Clark682c58d2018-05-16 07:07:07 -0400529Creates Image from pixmap. Image is uploaded to GPU back-end using context.
Cary Clark3cd22cc2017-12-01 11:49:58 -0500530
531Created Image is available to other GPU contexts, and is available across thread
Cary Clark682c58d2018-05-16 07:07:07 -0400532boundaries. All contexts must be in the same GPU_Share_Group, or otherwise
Cary Clark3cd22cc2017-12-01 11:49:58 -0500533share resources.
534
535When Image is no longer referenced, context releases texture memory
536asynchronously.
537
538Texture created from pixmap is uploaded to match Surface created with
539dstColorSpace. Color_Space of Image is determined by pixmap.colorSpace().
540
Cary Clark682c58d2018-05-16 07:07:07 -0400541Image is returned referring to GPU back-end if context is not nullptr,
Cary Clark61ca7c52018-01-02 11:34:14 -0500542format of data is recognized and supported, and if context supports moving
543resources between contexts. Otherwise, pixmap pixel data is copied and Image
544as returned in raster format if possible; nullptr may be returned.
545Recognized GPU formats vary by platform and GPU back-end.
Cary Clark3cd22cc2017-12-01 11:49:58 -0500546
547#Param context GPU_Context ##
548#Param pixmap Image_Info, pixel address, and row bytes ##
549#Param buildMips create Image as Mip_Map if true ##
550#Param dstColorSpace range of colors of matching Surface on GPU ##
Brian Osman584b5012018-04-13 15:48:26 -0400551#Param limitToMaxTextureSize downscale image to GPU maximum texture size, if necessary ##
Cary Clark3cd22cc2017-12-01 11:49:58 -0500552
553#Return created Image, or nullptr ##
554
555#Example
Cary Clark61ca7c52018-01-02 11:34:14 -0500556#Image 4
Cary Clarkac47b882018-01-11 10:35:44 -0500557#Height 64
Cary Clark61ca7c52018-01-02 11:34:14 -0500558GrContext* context = canvas->getGrContext();
559SkPixmap pixmap;
560if (source.peekPixels(&pixmap)) {
561 sk_sp<SkImage> image = SkImage::MakeCrossContextFromPixmap(context, pixmap,
562 false, nullptr);
563 canvas->drawImage(image, 0, 0);
564}
Cary Clark3cd22cc2017-12-01 11:49:58 -0500565##
566
567#SeeAlso MakeCrossContextFromEncoded
Cary Clarka560c472017-11-27 10:44:06 -0500568
569#Method ##
570
571# ------------------------------------------------------------------------------
572
573#Method static sk_sp<SkImage> MakeFromAdoptedTexture(GrContext* context,
574 const GrBackendTexture& backendTexture,
575 GrSurfaceOrigin surfaceOrigin,
Cary Clark61ca7c52018-01-02 11:34:14 -0500576 SkColorType colorType,
577 SkAlphaType alphaType = kPremul_SkAlphaType,
578 sk_sp<SkColorSpace> colorSpace = nullptr)
Cary Clark4855f782018-02-06 09:41:53 -0500579#In Constructor
580#Line # creates Image from GPU_Texture, managed internally ##
Cary Clark3cd22cc2017-12-01 11:49:58 -0500581Creates Image from backendTexture associated with context. backendTexture and
582returned Image are managed internally, and are released when no longer needed.
Cary Clarka560c472017-11-27 10:44:06 -0500583
Cary Clark3cd22cc2017-12-01 11:49:58 -0500584Image is returned if format of backendTexture is recognized and supported.
585Recognized formats vary by GPU back-end.
Cary Clarka560c472017-11-27 10:44:06 -0500586
Cary Clark3cd22cc2017-12-01 11:49:58 -0500587#Param context GPU_Context ##
588#Param backendTexture texture residing on GPU ##
589#Param surfaceOrigin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin ##
Cary Clark1a8d7622018-03-05 13:26:16 -0500590#Param colorType one of: #list_of_color_types#
Cary Clark61ca7c52018-01-02 11:34:14 -0500591##
Cary Clark681287e2018-03-16 11:34:15 -0400592#Param alphaType one of: #list_of_alpha_types#
Cary Clark3cd22cc2017-12-01 11:49:58 -0500593##
Cary Clark61ca7c52018-01-02 11:34:14 -0500594#Param colorSpace range of colors; may be nullptr ##
Cary Clark3cd22cc2017-12-01 11:49:58 -0500595
596#Return created Image, or nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -0500597
598#Example
Cary Clarkac47b882018-01-11 10:35:44 -0500599#Image 5
600#Platform gpu
Cary Clark61ca7c52018-01-02 11:34:14 -0500601 if (!canvas->getGrContext()) {
602 return;
603 }
604 canvas->scale(.5f, .5f);
605 canvas->clear(0x7f3f5f7f);
606 int x = 0, y = 0;
607 for (auto origin : { kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin } ) {
608 for (auto alpha : { kOpaque_SkAlphaType, kPremul_SkAlphaType, kUnpremul_SkAlphaType } ) {
609 sk_sp<SkImage> image = SkImage::MakeFromAdoptedTexture(canvas->getGrContext(),
Cary Clark682c58d2018-05-16 07:07:07 -0400610 backEndTexture, origin,
Cary Clark61ca7c52018-01-02 11:34:14 -0500611 kRGBA_8888_SkColorType, alpha);
612 canvas->drawImage(image, x, y);
613 x += 160;
614 }
615 x -= 160 * 3;
616 y += 256;
617 }
Cary Clarka560c472017-11-27 10:44:06 -0500618##
619
Cary Clark61ca7c52018-01-02 11:34:14 -0500620#SeeAlso MakeFromTexture MakeFromYUVTexturesCopy
Cary Clarka560c472017-11-27 10:44:06 -0500621
622#Method ##
623
624# ------------------------------------------------------------------------------
625
626#Method static sk_sp<SkImage> MakeFromYUVTexturesCopy(GrContext* context, SkYUVColorSpace yuvColorSpace,
Brian Salomon6a426c12018-03-15 12:16:02 -0400627 const GrBackendTexture yuvTextures[3],
Cary Clarka560c472017-11-27 10:44:06 -0500628 GrSurfaceOrigin surfaceOrigin,
629 sk_sp<SkColorSpace> colorSpace = nullptr)
Cary Clark4855f782018-02-06 09:41:53 -0500630#In Constructor
631#Line # creates Image from YUV_ColorSpace data in three planes ##
Cary Clarka560c472017-11-27 10:44:06 -0500632
Brian Salomon6a426c12018-03-15 12:16:02 -0400633Creates Image from copy of yuvTextures, an array of textures on GPU.
634yuvTextures contain pixels for YUV planes of Image. Returned Image has the dimensions
635yuvTextures[0]. yuvColorSpace describes how YUV colors convert to RGB colors.
Cary Clarka560c472017-11-27 10:44:06 -0500636
Cary Clark61ca7c52018-01-02 11:34:14 -0500637#Param context GPU_Context ##
638#Param yuvColorSpace one of: kJPEG_SkYUVColorSpace, kRec601_SkYUVColorSpace,
639 kRec709_SkYUVColorSpace
640##
Brian Salomon6a426c12018-03-15 12:16:02 -0400641#Param yuvTextures array of YUV textures on GPU ##
Cary Clark61ca7c52018-01-02 11:34:14 -0500642#Param surfaceOrigin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin ##
643#Param colorSpace range of colors; may be nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -0500644
Cary Clark61ca7c52018-01-02 11:34:14 -0500645#Return created Image, or nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -0500646
Cary Clark61ca7c52018-01-02 11:34:14 -0500647# seems too complicated to create an example for this
648#ToDo
649should this be moved to chrome only?
Cary Clarka560c472017-11-27 10:44:06 -0500650##
651
Cary Clark61ca7c52018-01-02 11:34:14 -0500652#NoExample
653##
654
655#SeeAlso MakeFromNV12TexturesCopy
656
657#Method ##
658
659# ------------------------------------------------------------------------------
660
Cary Clarka560c472017-11-27 10:44:06 -0500661#Method static sk_sp<SkImage> MakeFromNV12TexturesCopy(GrContext* context,
662 SkYUVColorSpace yuvColorSpace,
Brian Salomon6a426c12018-03-15 12:16:02 -0400663 const GrBackendTexture nv12Textures[2],
Cary Clarka560c472017-11-27 10:44:06 -0500664 GrSurfaceOrigin surfaceOrigin,
665 sk_sp<SkColorSpace> colorSpace = nullptr)
Cary Clark4855f782018-02-06 09:41:53 -0500666#In Constructor
Brian Salomon6a426c12018-03-15 12:16:02 -0400667#Line # creates Image from YUV_ColorSpace data in three planes ##
Cary Clarka560c472017-11-27 10:44:06 -0500668
Cary Clark681287e2018-03-16 11:34:15 -0400669Creates Image from copy of nv12Textures, an array of textures on GPU.
Brian Salomon6a426c12018-03-15 12:16:02 -0400670nv12Textures[0] contains pixels for YUV_Component_Y plane.
671nv12Textures[1] contains pixels for YUV_Component_U plane,
Cary Clark61ca7c52018-01-02 11:34:14 -0500672followed by pixels for YUV_Component_V plane.
Cary Clark681287e2018-03-16 11:34:15 -0400673Returned Image has the dimensions nv12Textures[2].
674yuvColorSpace describes how YUV colors convert to RGB colors.
Cary Clarka560c472017-11-27 10:44:06 -0500675
Cary Clark61ca7c52018-01-02 11:34:14 -0500676#Param context GPU_Context ##
677#Param yuvColorSpace one of: kJPEG_SkYUVColorSpace, kRec601_SkYUVColorSpace,
678 kRec709_SkYUVColorSpace
679##
Brian Salomon6a426c12018-03-15 12:16:02 -0400680#Param nv12Textures array of YUV textures on GPU ##
Cary Clark61ca7c52018-01-02 11:34:14 -0500681#Param surfaceOrigin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin ##
682#Param colorSpace range of colors; may be nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -0500683
Cary Clark61ca7c52018-01-02 11:34:14 -0500684#Return created Image, or nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -0500685
Cary Clark61ca7c52018-01-02 11:34:14 -0500686# seems too complicated to create an example for this
687#ToDo
688should this be moved to chrome only?
Cary Clarka560c472017-11-27 10:44:06 -0500689##
690
Cary Clark61ca7c52018-01-02 11:34:14 -0500691#NoExample
692##
693
694#SeeAlso MakeFromYUVTexturesCopy
Cary Clarka560c472017-11-27 10:44:06 -0500695
696#Method ##
697
698# ------------------------------------------------------------------------------
699
Cary Clark4855f782018-02-06 09:41:53 -0500700# currently uncalled by any test or client ##
Cary Clark61ca7c52018-01-02 11:34:14 -0500701#Bug 7424
Cary Clark61ca7c52018-01-02 11:34:14 -0500702
Cary Clark56356312018-02-08 14:45:18 -0500703#EnumClass BitDepth
Cary Clark682c58d2018-05-16 07:07:07 -0400704#Line # options for MakeFromPicture ##
Cary Clarka560c472017-11-27 10:44:06 -0500705#Code
Cary Clark61ca7c52018-01-02 11:34:14 -0500706 enum class BitDepth {
Cary Clarka560c472017-11-27 10:44:06 -0500707 kU8,
708 kF16,
709 };
710##
711
712#Const kU8 0
Cary Clark682c58d2018-05-16 07:07:07 -0400713#Line # uses 8-bit unsigned int per Color component ##
Cary Clarkffb3d682018-05-17 12:17:28 -0400714Use 8 bits per ARGB component using unsigned integer format.
Cary Clarka560c472017-11-27 10:44:06 -0500715##
716#Const kF16 1
Cary Clark682c58d2018-05-16 07:07:07 -0400717#Line # uses 16-bit float per Color component ##
Cary Clarkffb3d682018-05-17 12:17:28 -0400718Use 16 bits per ARGB component using half-precision floating point format.
Cary Clarka560c472017-11-27 10:44:06 -0500719##
720
Cary Clark61ca7c52018-01-02 11:34:14 -0500721#NoExample
Cary Clarka560c472017-11-27 10:44:06 -0500722##
723
Cary Clark61ca7c52018-01-02 11:34:14 -0500724#SeeAlso MakeFromPicture
Cary Clarka560c472017-11-27 10:44:06 -0500725
Cary Clark56356312018-02-08 14:45:18 -0500726#EnumClass ##
Cary Clarka560c472017-11-27 10:44:06 -0500727
728# ------------------------------------------------------------------------------
729
730#Method static sk_sp<SkImage> MakeFromPicture(sk_sp<SkPicture> picture, const SkISize& dimensions,
731 const SkMatrix* matrix, const SkPaint* paint,
732 BitDepth bitDepth,
733 sk_sp<SkColorSpace> colorSpace)
Cary Clark4855f782018-02-06 09:41:53 -0500734#In Constructor
735#Line # creates Image from Picture ##
Cary Clarka560c472017-11-27 10:44:06 -0500736
Cary Clark61ca7c52018-01-02 11:34:14 -0500737Creates Image from picture. Returned Image width and height are set by dimensions.
738Image draws picture with matrix and paint, set to bitDepth and colorSpace.
Cary Clarka560c472017-11-27 10:44:06 -0500739
Cary Clark61ca7c52018-01-02 11:34:14 -0500740If matrix is nullptr, draws with identity Matrix. If paint is nullptr, draws
Cary Clark682c58d2018-05-16 07:07:07 -0400741with default Paint. colorSpace may be nullptr.
Cary Clarka560c472017-11-27 10:44:06 -0500742
Cary Clark61ca7c52018-01-02 11:34:14 -0500743#Param picture stream of drawing commands ##
744#Param dimensions width and height ##
745#Param matrix Matrix to rotate, scale, translate, and so on; may be nullptr ##
746#Param paint Paint to apply transparency, filtering, and so on; may be nullptr ##
Cary Clark682c58d2018-05-16 07:07:07 -0400747#Param bitDepth 8-bit integer or 16-bit float: per component ##
Cary Clark61ca7c52018-01-02 11:34:14 -0500748#Param colorSpace range of colors; may be nullptr ##
749
750#Return created Image, or nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -0500751
752#Example
Cary Clark61ca7c52018-01-02 11:34:14 -0500753 SkPaint paint;
754 SkPictureRecorder recorder;
755 SkCanvas* recordingCanvas = recorder.beginRecording(50, 50);
756 for (auto color : { SK_ColorRED, SK_ColorBLUE, 0xff007f00 } ) {
757 paint.setColor(color);
758 recordingCanvas->drawRect({10, 10, 30, 40}, paint);
759 recordingCanvas->translate(10, 10);
760 recordingCanvas->scale(1.2f, 1.4f);
761 }
762 sk_sp<SkPicture> playback = recorder.finishRecordingAsPicture();
763 int x = 0, y = 0;
764 for (auto alpha : { 70, 140, 210 } ) {
765 paint.setAlpha(alpha);
766 auto srgbColorSpace = SkColorSpace::MakeSRGB();
767 sk_sp<SkImage> image = SkImage::MakeFromPicture(playback, {50, 50}, nullptr, &paint,
768 SkImage::BitDepth::kU8, srgbColorSpace);
769 canvas->drawImage(image, x, y);
770 x += 70; y += 70;
771 }
Cary Clarka560c472017-11-27 10:44:06 -0500772##
773
Cary Clark61ca7c52018-01-02 11:34:14 -0500774#SeeAlso SkCanvas::drawPicture
Cary Clarka560c472017-11-27 10:44:06 -0500775
776#Method ##
777
778# ------------------------------------------------------------------------------
779
780#Method static sk_sp<SkImage> MakeFromAHardwareBuffer(AHardwareBuffer* hardwareBuffer,
781 SkAlphaType alphaType = kPremul_SkAlphaType,
782 sk_sp<SkColorSpace> colorSpace = nullptr)
Cary Clark4855f782018-02-06 09:41:53 -0500783#In Constructor
784#Line # creates Image from Android hardware buffer ##
Cary Clarka560c472017-11-27 10:44:06 -0500785
Cary Clark4855f782018-02-06 09:41:53 -0500786#Bug 7447
Cary Clarka560c472017-11-27 10:44:06 -0500787
Cary Clark61ca7c52018-01-02 11:34:14 -0500788Creates Image from Android hardware buffer.
789Returned Image takes a reference on the buffer.
Cary Clarka560c472017-11-27 10:44:06 -0500790
Cary Clark61ca7c52018-01-02 11:34:14 -0500791Only available on Android, when __ANDROID_API__ is defined to be 26 or greater.
Cary Clarka560c472017-11-27 10:44:06 -0500792
Cary Clark61ca7c52018-01-02 11:34:14 -0500793#Param hardwareBuffer AHardwareBuffer Android hardware buffer ##
Cary Clark681287e2018-03-16 11:34:15 -0400794#Param alphaType one of: #list_of_alpha_types#
Cary Clark61ca7c52018-01-02 11:34:14 -0500795##
796#Param colorSpace range of colors; may be nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -0500797
Cary Clark61ca7c52018-01-02 11:34:14 -0500798#Return created Image, or nullptr ##
799
800#NoExample
Cary Clarka560c472017-11-27 10:44:06 -0500801##
802
Cary Clark61ca7c52018-01-02 11:34:14 -0500803#SeeAlso MakeFromRaster
Cary Clarka560c472017-11-27 10:44:06 -0500804
805#Method ##
806
807# ------------------------------------------------------------------------------
Cary Clark4855f782018-02-06 09:41:53 -0500808#Subtopic Property
809#Populate
810#Line # values and attributes ##
811##
Cary Clarka560c472017-11-27 10:44:06 -0500812
813#Method int width() const
Cary Clark4855f782018-02-06 09:41:53 -0500814#In Property
815#Line # returns pixel column count ##
Cary Clark61ca7c52018-01-02 11:34:14 -0500816Returns pixel count in each row.
817
818#Return pixel width in Image ##
Cary Clarka560c472017-11-27 10:44:06 -0500819
820#Example
Cary Clark61ca7c52018-01-02 11:34:14 -0500821#Image 4
Cary Clarkac47b882018-01-11 10:35:44 -0500822#Height 96
Cary Clark61ca7c52018-01-02 11:34:14 -0500823 canvas->translate(10, 10);
824 canvas->drawImage(image, 0, 0);
825 canvas->translate(0, image->height());
826 SkPaint paint;
827 paint.setTextAlign(SkPaint::kCenter_Align);
828 canvas->drawLine(0, 10, image->width(), 10, paint);
829 canvas->drawString("width", image->width() / 2, 25, paint);
Cary Clarka560c472017-11-27 10:44:06 -0500830##
831
Cary Clark61ca7c52018-01-02 11:34:14 -0500832#SeeAlso dimensions() height()
Cary Clarka560c472017-11-27 10:44:06 -0500833
834#Method ##
835
836# ------------------------------------------------------------------------------
837
838#Method int height() const
Cary Clark4855f782018-02-06 09:41:53 -0500839#In Property
840#Line # returns pixel row count ##
Cary Clark2f466242017-12-11 16:03:17 -0500841Returns pixel row count.
842
Cary Clark61ca7c52018-01-02 11:34:14 -0500843#Return pixel height in Image ##
Cary Clarka560c472017-11-27 10:44:06 -0500844
845#Example
Cary Clark61ca7c52018-01-02 11:34:14 -0500846#Image 4
Cary Clarkac47b882018-01-11 10:35:44 -0500847#Height 96
Cary Clark61ca7c52018-01-02 11:34:14 -0500848 canvas->translate(10, 10);
849 canvas->drawImage(image, 0, 0);
850 canvas->translate(image->width(), 0);
851 SkPaint paint;
852 paint.setTextAlign(SkPaint::kCenter_Align);
853 paint.setVerticalText(true);
854 canvas->drawLine(10, 0, 10, image->height(), paint);
Cary Clarkac47b882018-01-11 10:35:44 -0500855 canvas->drawString("height", 25, image->height() / 2, paint);
856##
Cary Clarka560c472017-11-27 10:44:06 -0500857
Cary Clark61ca7c52018-01-02 11:34:14 -0500858#SeeAlso dimensions() width()
Cary Clarka560c472017-11-27 10:44:06 -0500859
860#Method ##
861
862# ------------------------------------------------------------------------------
863
864#Method SkISize dimensions() const
Cary Clark4855f782018-02-06 09:41:53 -0500865#In Property
866#Line # returns width() and height() ##
Cary Clark681287e2018-03-16 11:34:15 -0400867
Cary Clark2f466242017-12-11 16:03:17 -0500868Returns ISize { width(), height() }.
869
870#Return integral size of width() and height() ##
Cary Clarka560c472017-11-27 10:44:06 -0500871
872#Example
Cary Clark61ca7c52018-01-02 11:34:14 -0500873#Image 4
874 SkISize dimensions = image->dimensions();
875 SkIRect bounds = image->bounds();
876 SkIRect dimensionsAsBounds = SkIRect::MakeSize(dimensions);
877 SkDebugf("dimensionsAsBounds %c= bounds\n", dimensionsAsBounds == bounds ? '=' : '!');
Cary Clark681287e2018-03-16 11:34:15 -0400878#StdOut
879dimensionsAsBounds == bounds
880##
Cary Clarka560c472017-11-27 10:44:06 -0500881##
882
Cary Clark61ca7c52018-01-02 11:34:14 -0500883#SeeAlso height() width() bounds()
Cary Clarka560c472017-11-27 10:44:06 -0500884
885#Method ##
886
887# ------------------------------------------------------------------------------
888
889#Method SkIRect bounds() const
Cary Clark4855f782018-02-06 09:41:53 -0500890#In Property
891#Line # returns width() and height() as Rectangle ##
Cary Clark2f466242017-12-11 16:03:17 -0500892Returns IRect { 0, 0, width(), height() }.
893
894#Return integral rectangle from origin to width() and height() ##
Cary Clarka560c472017-11-27 10:44:06 -0500895
896#Example
Cary Clark61ca7c52018-01-02 11:34:14 -0500897#Height 128
898#Image 4
Cary Clark61ca7c52018-01-02 11:34:14 -0500899 SkIRect bounds = image->bounds();
Cary Clarkac47b882018-01-11 10:35:44 -0500900 for (int x : { 0, bounds.width() } ) {
901 for (int y : { 0, bounds.height() } ) {
Cary Clark61ca7c52018-01-02 11:34:14 -0500902 canvas->drawImage(image, x, y);
903 }
904 }
Cary Clarka560c472017-11-27 10:44:06 -0500905##
906
Cary Clark682c58d2018-05-16 07:07:07 -0400907#SeeAlso dimensions()
Cary Clarka560c472017-11-27 10:44:06 -0500908
909#Method ##
910
911# ------------------------------------------------------------------------------
912
913#Method uint32_t uniqueID() const
Cary Clark4855f782018-02-06 09:41:53 -0500914#In Property
Cary Clark682c58d2018-05-16 07:07:07 -0400915#Line # returns identifier for Image ##
Cary Clark61ca7c52018-01-02 11:34:14 -0500916Returns value unique to image. Image contents cannot change after Image is
917created. Any operation to create a new Image will receive generate a new
918unique number.
919
920#Return unique identifier ##
Cary Clarka560c472017-11-27 10:44:06 -0500921
922#Example
Cary Clark61ca7c52018-01-02 11:34:14 -0500923#Image 5
924#Height 156
925 sk_sp<SkImage> subset = image->makeSubset({10, 20, 90, 100});
926 canvas->drawImage(image, 0, 0);
927 canvas->drawImage(subset, 128, 0);
928 SkPaint paint;
929 SkString s;
930 s.printf("original id: %d", image->uniqueID());
931 canvas->drawString(s, 20, image->height() + 20, paint);
932 s.printf("subset id: %d", subset->uniqueID());
933 canvas->drawString(s, 148, subset->height() + 20, paint);
Cary Clarka560c472017-11-27 10:44:06 -0500934##
935
Cary Clark61ca7c52018-01-02 11:34:14 -0500936#SeeAlso isLazyGenerated
Cary Clarka560c472017-11-27 10:44:06 -0500937
938#Method ##
939
940# ------------------------------------------------------------------------------
941
942#Method SkAlphaType alphaType() const
Cary Clark4855f782018-02-06 09:41:53 -0500943#In Property
944#Line # returns Alpha_Type ##
Cary Clark681287e2018-03-16 11:34:15 -0400945Returns Alpha_Type, one of: #list_of_alpha_types#.
Cary Clark61ca7c52018-01-02 11:34:14 -0500946
947Alpha_Type returned was a parameter to an Image constructor,
948or was parsed from encoded data.
949
950#Return Alpha_Type in Image ##
Cary Clarka560c472017-11-27 10:44:06 -0500951
952#Example
Cary Clark61ca7c52018-01-02 11:34:14 -0500953#Image 4
Cary Clarkac47b882018-01-11 10:35:44 -0500954#Height 96
Cary Clark61ca7c52018-01-02 11:34:14 -0500955 const char* alphaTypeStr[] = { "Unknown", "Opaque", "Premul", "Unpremul" };
956 SkAlphaType alphaType = image->alphaType();
Cary Clarkac47b882018-01-11 10:35:44 -0500957 canvas->drawImage(image, 16, 0);
Cary Clarkffb3d682018-05-17 12:17:28 -0400958 canvas->drawString(alphaTypeStr[(int) alphaType], 20, image->height() + 20, SkPaint());
Cary Clarka560c472017-11-27 10:44:06 -0500959##
960
Cary Clark61ca7c52018-01-02 11:34:14 -0500961#SeeAlso SkImageInfo::alphaType
Cary Clarka560c472017-11-27 10:44:06 -0500962
963#Method ##
964
965# ------------------------------------------------------------------------------
966
Greg Daniel56008aa2018-03-14 15:33:42 -0400967#Method SkColorType colorType() const
968#In Property
969#Line # returns Color_Type ##
970
971Returns Color_Type if known; otherwise, returns kUnknown_SkColorType.
972
973#Return Color_Type of Image ##
974
975#Example
Cary Clarkffb3d682018-05-17 12:17:28 -0400976#Image 4
977#Height 96
978 const char* colors[] = { "Unknown", "Alpha_8", "RGB_565", "ARGB_4444", "RGBA_8888", "RGB_888x",
979 "BGRA_8888", "RGBA_1010102", "RGB_101010x", "Gray_8", "RGBA_F16" };
980 SkColorType colorType = image->colorType();
981 canvas->drawImage(image, 16, 0);
982 canvas->drawString(colors[(int) colorType], 20, image->height() + 20, SkPaint());
Greg Daniel56008aa2018-03-14 15:33:42 -0400983##
984
985#SeeAlso SkImageInfo::colorType
986
987#Method ##
988
989# ------------------------------------------------------------------------------
990
Cary Clarka560c472017-11-27 10:44:06 -0500991#Method SkColorSpace* colorSpace() const
Cary Clark4855f782018-02-06 09:41:53 -0500992#In Property
993#Line # returns Color_Space ##
Cary Clark2f466242017-12-11 16:03:17 -0500994Returns Color_Space, the range of colors, associated with Image. The
995reference count of Color_Space is unchanged. The returned Color_Space is
996immutable.
Cary Clarka560c472017-11-27 10:44:06 -0500997
Cary Clark61dfc3a2018-01-03 08:37:53 -0500998Color_Space returned was passed to an Image constructor,
999or was parsed from encoded data. Color_Space returned may be ignored when Image
1000is drawn, depending on the capabilities of the Surface receiving the drawing.
Cary Clark2f466242017-12-11 16:03:17 -05001001
1002#Return Color_Space in Image, or nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -05001003
1004#Example
Cary Clark61dfc3a2018-01-03 08:37:53 -05001005#Image 3
1006#Set sRGB
1007 SkPixmap pixmap;
1008 source.peekPixels(&pixmap);
1009 canvas->scale(.25f, .25f);
1010 int y = 0;
1011 for (auto gamma : { SkColorSpace::kLinear_RenderTargetGamma,
1012 SkColorSpace::kSRGB_RenderTargetGamma } ) {
1013 int x = 0;
1014 sk_sp<SkColorSpace> colorSpace = SkColorSpace::MakeRGB(gamma, SkColorSpace::kSRGB_Gamut);
1015 for (int index = 0; index < 2; ++index) {
1016 pixmap.setColorSpace(colorSpace);
1017 sk_sp<SkImage> image = SkImage::MakeRasterCopy(pixmap);
1018 canvas->drawImage(image, x, y);
1019 colorSpace = image->colorSpace()->makeColorSpin();
1020 x += 512;
1021 }
1022 y += 512;
1023 }
Cary Clarka560c472017-11-27 10:44:06 -05001024##
1025
Cary Clark61dfc3a2018-01-03 08:37:53 -05001026#SeeAlso refColorSpace makeColorSpace
Cary Clarka560c472017-11-27 10:44:06 -05001027
1028#Method ##
1029
1030# ------------------------------------------------------------------------------
1031
1032#Method sk_sp<SkColorSpace> refColorSpace() const
Cary Clark4855f782018-02-06 09:41:53 -05001033#In Property
1034#Line # returns Image_Info Color_Space ##
Cary Clark61dfc3a2018-01-03 08:37:53 -05001035Returns a smart pointer to Color_Space, the range of colors, associated with
1036Image. The smart pointer tracks the number of objects sharing this
1037SkColorSpace reference so the memory is released when the owners destruct.
1038
1039The returned SkColorSpace is immutable.
1040
1041Color_Space returned was passed to an Image constructor,
1042or was parsed from encoded data. Color_Space returned may be ignored when Image
1043is drawn, depending on the capabilities of the Surface receiving the drawing.
1044
1045#Return Color_Space in Image, or nullptr, wrapped in a smart pointer ##
Cary Clarka560c472017-11-27 10:44:06 -05001046
1047#Example
Cary Clark61dfc3a2018-01-03 08:37:53 -05001048#Image 3
1049#Set sRGB
1050 SkPixmap pixmap;
1051 source.peekPixels(&pixmap);
1052 canvas->scale(.25f, .25f);
1053 int y = 0;
1054 for (auto gamma : { SkColorSpace::kLinear_RenderTargetGamma,
1055 SkColorSpace::kSRGB_RenderTargetGamma } ) {
1056 int x = 0;
1057 sk_sp<SkColorSpace> colorSpace = SkColorSpace::MakeRGB(gamma, SkColorSpace::kSRGB_Gamut);
1058 for (int index = 0; index < 2; ++index) {
1059 pixmap.setColorSpace(colorSpace);
1060 sk_sp<SkImage> image = SkImage::MakeRasterCopy(pixmap);
1061 canvas->drawImage(image, x, y);
1062 colorSpace = image->refColorSpace()->makeColorSpin();
1063 x += 512;
1064 }
1065 y += 512;
1066 }
Cary Clarka560c472017-11-27 10:44:06 -05001067##
1068
Cary Clark61dfc3a2018-01-03 08:37:53 -05001069#SeeAlso colorSpace makeColorSpace
Cary Clarka560c472017-11-27 10:44:06 -05001070
1071#Method ##
1072
1073# ------------------------------------------------------------------------------
1074
1075#Method bool isAlphaOnly() const
Cary Clark4855f782018-02-06 09:41:53 -05001076#In Property
1077#Line # returns if pixels represent a transparency mask ##
Cary Clark2f466242017-12-11 16:03:17 -05001078Returns true if Image pixels represent transparency only. If true, each pixel
1079is packed in 8 bits as defined by kAlpha_8_SkColorType.
Cary Clarka560c472017-11-27 10:44:06 -05001080
Cary Clark2f466242017-12-11 16:03:17 -05001081#Return true if pixels represent a transparency mask ##
Cary Clarka560c472017-11-27 10:44:06 -05001082
1083#Example
Cary Clark61dfc3a2018-01-03 08:37:53 -05001084 uint8_t pmColors = 0;
1085 sk_sp<SkImage> image = SkImage::MakeRasterCopy({SkImageInfo::MakeA8(1, 1), &pmColors, 1});
1086 SkDebugf("alphaOnly = %s\n", image->isAlphaOnly() ? "true" : "false");
1087#StdOut
1088alphaOnly = true
1089##
Cary Clarka560c472017-11-27 10:44:06 -05001090##
1091
Cary Clark61dfc3a2018-01-03 08:37:53 -05001092#SeeAlso alphaType isOpaque
Cary Clarka560c472017-11-27 10:44:06 -05001093
1094#Method ##
1095
1096# ------------------------------------------------------------------------------
1097
1098#Method bool isOpaque() const
Cary Clark4855f782018-02-06 09:41:53 -05001099#In Property
1100#Line # returns if Alpha_Type is kOpaque_SkAlphaType ##
Cary Clark61dfc3a2018-01-03 08:37:53 -05001101Returns true if pixels ignore their Alpha value and are treated as fully opaque.
Cary Clark2f466242017-12-11 16:03:17 -05001102
1103#Return true if Alpha_Type is kOpaque_SkAlphaType ##
Cary Clarka560c472017-11-27 10:44:06 -05001104
1105#Example
Cary Clark61dfc3a2018-01-03 08:37:53 -05001106 auto check_isopaque = [](const SkImageInfo& imageInfo) -> void {
1107 auto surface(SkSurface::MakeRaster(imageInfo));
1108 auto image(surface->makeImageSnapshot());
1109 SkDebugf("isOpaque = %s\n", image->isOpaque() ? "true" : "false");
1110 };
1111
1112 check_isopaque(SkImageInfo::MakeN32Premul(5, 5));
1113 check_isopaque(SkImageInfo::MakeN32(5, 5, kOpaque_SkAlphaType));
1114#StdOut
1115isOpaque = false
1116isOpaque = true
1117##
Cary Clarka560c472017-11-27 10:44:06 -05001118##
1119
Cary Clark61dfc3a2018-01-03 08:37:53 -05001120#SeeAlso alphaType isAlphaOnly
Cary Clarka560c472017-11-27 10:44:06 -05001121
1122#Method ##
1123
1124# ------------------------------------------------------------------------------
1125
1126#Method sk_sp<SkShader> makeShader(SkShader::TileMode tileMode1, SkShader::TileMode tileMode2,
1127 const SkMatrix* localMatrix = nullptr) const
Cary Clark4855f782018-02-06 09:41:53 -05001128#In Constructor
1129#Line # creates Shader, Paint element that can tile Image ##
Cary Clarka560c472017-11-27 10:44:06 -05001130
Cary Clark61dfc3a2018-01-03 08:37:53 -05001131Creates Shader from Image. Shader dimensions are taken from Image. Shader uses
1132SkShader::TileMode rules to fill drawn area outside Image. localMatrix permits
1133transforming Image before Canvas_Matrix is applied.
Cary Clarka560c472017-11-27 10:44:06 -05001134
Cary Clark61dfc3a2018-01-03 08:37:53 -05001135#Param tileMode1 tiling in x, one of: SkShader::kClamp_TileMode, SkShader::kRepeat_TileMode,
1136 SkShader::kMirror_TileMode
1137##
1138#Param tileMode2 tiling in y, one of: SkShader::kClamp_TileMode, SkShader::kRepeat_TileMode,
1139 SkShader::kMirror_TileMode
1140##
1141#Param localMatrix Image transformation, or nullptr ##
1142
1143#Return Shader containing Image ##
Cary Clarka560c472017-11-27 10:44:06 -05001144
1145#Example
Cary Clark61dfc3a2018-01-03 08:37:53 -05001146#Image 4
1147SkMatrix matrix;
1148matrix.setRotate(45);
1149SkPaint paint;
1150paint.setShader(image->makeShader(SkShader::kRepeat_TileMode, SkShader::kMirror_TileMode,
1151 &matrix));
1152canvas->drawPaint(paint);
Cary Clarka560c472017-11-27 10:44:06 -05001153##
1154
Cary Clark61dfc3a2018-01-03 08:37:53 -05001155#SeeAlso scalePixels
Cary Clarka560c472017-11-27 10:44:06 -05001156
1157#Method ##
1158
1159# ------------------------------------------------------------------------------
1160
1161#Method sk_sp<SkShader> makeShader(const SkMatrix* localMatrix = nullptr) const
1162
Cary Clark61dfc3a2018-01-03 08:37:53 -05001163Creates Shader from Image. Shader dimensions are taken from Image. Shader uses
1164SkShader::kClamp_TileMode to fill drawn area outside Image. localMatrix permits
1165transforming Image before Canvas_Matrix is applied.
Cary Clarka560c472017-11-27 10:44:06 -05001166
Cary Clark61dfc3a2018-01-03 08:37:53 -05001167#Param localMatrix Image transformation, or nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -05001168
Cary Clark61dfc3a2018-01-03 08:37:53 -05001169#Return Shader containing Image ##
Cary Clarka560c472017-11-27 10:44:06 -05001170
1171#Example
Cary Clark61dfc3a2018-01-03 08:37:53 -05001172#Image 5
1173SkMatrix matrix;
1174matrix.setRotate(45);
1175matrix.postTranslate(125, 30);
1176SkPaint paint;
1177paint.setShader(image->makeShader(&matrix));
1178canvas->drawPaint(paint);
Cary Clarka560c472017-11-27 10:44:06 -05001179##
1180
Cary Clarkf5404bb2018-01-05 12:10:09 -05001181#SeeAlso scalePixels
Cary Clarka560c472017-11-27 10:44:06 -05001182
1183#Method ##
1184
1185# ------------------------------------------------------------------------------
Cary Clark78de7512018-02-07 07:27:09 -05001186#Subtopic Pixels
1187#Populate
1188#Line # read and write pixel values ##
1189##
Cary Clarka560c472017-11-27 10:44:06 -05001190
1191#Method bool peekPixels(SkPixmap* pixmap) const
Cary Clark78de7512018-02-07 07:27:09 -05001192#In Pixels
Cary Clark4855f782018-02-06 09:41:53 -05001193#Line # returns Pixmap if possible ##
Cary Clarkf5404bb2018-01-05 12:10:09 -05001194Copies Image pixel address, row bytes, and Image_Info to pixmap, if address
1195is available, and returns true. If pixel address is not available, return
1196false and leave pixmap unchanged.
Cary Clarka560c472017-11-27 10:44:06 -05001197
Cary Clarkf5404bb2018-01-05 12:10:09 -05001198#Param pixmap storage for pixel state if pixels are readable; otherwise, ignored ##
Cary Clarka560c472017-11-27 10:44:06 -05001199
Cary Clarkf5404bb2018-01-05 12:10:09 -05001200#Return true if Image has direct access to pixels ##
Cary Clarka560c472017-11-27 10:44:06 -05001201
1202#Example
Cary Clarkf5404bb2018-01-05 12:10:09 -05001203 SkBitmap bitmap;
1204 bitmap.allocPixels(SkImageInfo::MakeN32Premul(12, 11));
1205 SkCanvas offscreen(bitmap);
1206 offscreen.clear(SK_ColorWHITE);
1207 SkPaint paint;
1208 offscreen.drawString("%", 1, 10, paint);
1209 sk_sp<SkImage> image = SkImage::MakeFromBitmap(bitmap);
1210 SkPixmap pixmap;
1211 if (image->peekPixels(&pixmap)) {
1212 const SkPMColor* pixels = pixmap.addr32();
1213 SkPMColor pmWhite = pixels[0];
1214 for (int y = 0; y < image->height(); ++y) {
1215 for (int x = 0; x < image->width(); ++x) {
1216 SkDebugf("%c", *pixels++ == pmWhite ? '-' : 'x');
1217 }
1218 SkDebugf("\n");
1219 }
1220 }
1221#StdOut
1222------------
1223--xx----x---
1224-x--x--x----
1225-x--x--x----
1226-x--x-x-----
1227--xx-xx-xx--
1228-----x-x--x-
1229----x--x--x-
1230----x--x--x-
1231---x----xx--
1232------------
1233##
Cary Clarka560c472017-11-27 10:44:06 -05001234##
1235
Cary Clarkf5404bb2018-01-05 12:10:09 -05001236#SeeAlso readPixels
Cary Clarka560c472017-11-27 10:44:06 -05001237
1238#Method ##
1239
1240# ------------------------------------------------------------------------------
1241
1242#Method GrTexture* getTexture() const
Cary Clark682c58d2018-05-16 07:07:07 -04001243#Deprecated
Cary Clarka560c472017-11-27 10:44:06 -05001244#Method ##
1245
1246# ------------------------------------------------------------------------------
1247
1248#Method bool isTextureBacked() const
Cary Clark78de7512018-02-07 07:27:09 -05001249#In Property
Cary Clark4855f782018-02-06 09:41:53 -05001250#Line # returns if Image was created from GPU_Texture ##
Cary Clarkf5404bb2018-01-05 12:10:09 -05001251Returns true the contents of Image was created on or uploaded to GPU memory,
1252and is available as a GPU_Texture.
Cary Clarka560c472017-11-27 10:44:06 -05001253
Cary Clarkf5404bb2018-01-05 12:10:09 -05001254#Return true if Image is a GPU_Texture ##
Cary Clarka560c472017-11-27 10:44:06 -05001255
1256#Example
Cary Clarkf5404bb2018-01-05 12:10:09 -05001257#Image 5
1258#Platform gpu
1259auto drawImage = [=](sk_sp<SkImage> image, const char* label) -> void {
1260 if (nullptr == image) {
1261 return;
1262 }
1263 SkPaint paint;
1264 paint.setAntiAlias(true);
1265 paint.setTextAlign(SkPaint::kCenter_Align);
1266 canvas->drawImage(image, 0, 0);
1267 canvas->drawString(label, image->width() / 2, image->height() / 4, paint);
1268 canvas->drawString(image->isTextureBacked() ? "is GPU texture" : "not GPU texture",
1269 image->width() / 2, image->height() * 3 / 4, paint);
1270};
1271sk_sp<SkImage> bitmapImage(SkImage::MakeFromBitmap(source));
1272sk_sp<SkImage> textureImage(SkImage::MakeFromTexture(canvas->getGrContext(), backEndTexture,
Cary Clark471b6fe2018-03-21 08:52:41 -04001273 kTopLeft_GrSurfaceOrigin, kN32_SkColorType, kOpaque_SkAlphaType,
1274 nullptr));
Cary Clarkf5404bb2018-01-05 12:10:09 -05001275drawImage(image, "image");
1276canvas->translate(image->width(), 0);
1277drawImage(bitmapImage, "source");
1278canvas->translate(-image->width(), image->height());
1279drawImage(textureImage, "backEndTexture");
Cary Clarka560c472017-11-27 10:44:06 -05001280##
1281
Cary Clarkf5404bb2018-01-05 12:10:09 -05001282#SeeAlso MakeFromTexture isValid
Cary Clarka560c472017-11-27 10:44:06 -05001283
1284#Method ##
1285
1286# ------------------------------------------------------------------------------
1287
1288#Method bool isValid(GrContext* context) const
Cary Clark4855f782018-02-06 09:41:53 -05001289#In Property
1290#Line # returns if Image can draw to Raster_Surface or GPU_Context ##
Cary Clarkf5404bb2018-01-05 12:10:09 -05001291Returns true if Image can be drawn on either Raster_Surface or GPU_Surface.
1292If context is nullptr, tests if Image draws on Raster_Surface;
1293otherwise, tests if Image draws on GPU_Surface associated with context.
Cary Clarka560c472017-11-27 10:44:06 -05001294
Cary Clarkf5404bb2018-01-05 12:10:09 -05001295Image backed by GPU_Texture may become invalid if associated GrContext is
1296invalid. Lazy_Image may be invalid and may not draw to Raster_Surface or
1297GPU_Surface or both.
Cary Clarka560c472017-11-27 10:44:06 -05001298
Cary Clark61ca7c52018-01-02 11:34:14 -05001299#Param context GPU_Context ##
Cary Clarka560c472017-11-27 10:44:06 -05001300
Cary Clarkf5404bb2018-01-05 12:10:09 -05001301#Return true if Image can be drawn ##
Cary Clarka560c472017-11-27 10:44:06 -05001302
1303#Example
Cary Clarkf5404bb2018-01-05 12:10:09 -05001304#Image 5
1305#Platform gpu
1306auto drawImage = [=](sk_sp<SkImage> image, const char* label) -> void {
1307 if (nullptr == image) {
1308 return;
1309 }
1310 SkPaint paint;
1311 paint.setAntiAlias(true);
1312 paint.setTextAlign(SkPaint::kCenter_Align);
1313 canvas->drawImage(image, 0, 0);
1314 canvas->drawString(label, image->width() / 2, image->height() / 4, paint);
1315 if (canvas->getGrContext()) {
1316 canvas->drawString(image->isValid(canvas->getGrContext()) ? "is valid on GPU" :
1317 "not valid on GPU", image->width() / 2, image->height() * 5 / 8, paint);
1318 }
1319 canvas->drawString(image->isValid(nullptr) ? "is valid on CPU" :
1320 "not valid on CPU", image->width() / 2, image->height() * 7 / 8, paint);
1321};
1322sk_sp<SkImage> bitmapImage(SkImage::MakeFromBitmap(source));
1323sk_sp<SkImage> textureImage(SkImage::MakeFromTexture(canvas->getGrContext(), backEndTexture,
Cary Clark471b6fe2018-03-21 08:52:41 -04001324 kTopLeft_GrSurfaceOrigin, kN32_SkColorType, kOpaque_SkAlphaType,
1325 nullptr));
Cary Clarkf5404bb2018-01-05 12:10:09 -05001326drawImage(image, "image");
1327canvas->translate(image->width(), 0);
1328drawImage(bitmapImage, "source");
1329canvas->translate(-image->width(), image->height());
1330drawImage(textureImage, "backEndTexture");
Cary Clarka560c472017-11-27 10:44:06 -05001331##
1332
Cary Clarkf5404bb2018-01-05 12:10:09 -05001333#SeeAlso isTextureBacked isLazyGenerated
Cary Clarka560c472017-11-27 10:44:06 -05001334
1335#Method ##
1336
1337# ------------------------------------------------------------------------------
1338
Brian Osmana0ca9092018-05-10 22:04:08 +00001339#Method GrBackendObject getTextureHandle(bool flushPendingGrContextIO,
1340 GrSurfaceOrigin* origin = nullptr) const
1341#Deprecated
1342#Method ##
1343
1344# ------------------------------------------------------------------------------
1345
Robert Phillipsc5509952018-04-04 15:54:55 -04001346#Method GrBackendTexture getBackendTexture(bool flushPendingGrContextIO,
1347 GrSurfaceOrigin* origin = nullptr) const
1348#In Property
1349#Line # returns GPU reference to Image as texture ##
1350
Cary Clark682c58d2018-05-16 07:07:07 -04001351Retrieves the back-end texture. If Image has no back-end texture, an invalid
Cary Clarkba75aee2018-04-05 08:18:41 -04001352object is returned. Call GrBackendTexture::isValid to determine if the result
1353is valid.
1354
1355If flushPendingGrContextIO is true, completes deferred I/O operations.
Robert Phillipsc5509952018-04-04 15:54:55 -04001356
1357If origin in not nullptr, copies location of content drawn into Image.
1358
1359#Param flushPendingGrContextIO flag to flush outstanding requests ##
1360#Param origin storage for one of: kTopLeft_GrSurfaceOrigin,
1361 kBottomLeft_GrSurfaceOrigin; or nullptr
1362##
1363
Cary Clarkba75aee2018-04-05 08:18:41 -04001364#Return back-end API texture handle; invalid on failure ##
Robert Phillipsc5509952018-04-04 15:54:55 -04001365
Cary Clarkba75aee2018-04-05 08:18:41 -04001366#Example
1367#Image 3
1368#Platform gpu
Brian Osman584b5012018-04-13 15:48:26 -04001369 GrContext* grContext = canvas->getGrContext();
1370 if (!grContext) {
1371 canvas->drawString("GPU only!", 20, 40, SkPaint());
1372 return;
1373 }
1374 sk_sp<SkImage> imageFromBackend = SkImage::MakeFromAdoptedTexture(grContext, backEndTexture,
1375 kBottomLeft_GrSurfaceOrigin, kRGBA_8888_SkColorType, kOpaque_SkAlphaType);
1376 GrBackendTexture textureFromImage = imageFromBackend->getBackendTexture(false);
1377 if (!textureFromImage.isValid()) {
1378 return;
1379 }
1380 sk_sp<SkImage> imageFromTexture = SkImage::MakeFromAdoptedTexture(grContext, textureFromImage,
1381 kTopLeft_GrSurfaceOrigin, kRGBA_8888_SkColorType, kOpaque_SkAlphaType);
1382 canvas->drawImage(imageFromTexture, 0, 0);
Cary Clarkba75aee2018-04-05 08:18:41 -04001383 canvas->drawImage(imageFromBackend, 128, 128);
Robert Phillipsc5509952018-04-04 15:54:55 -04001384##
1385
1386#SeeAlso MakeFromTexture isTextureBacked
1387
1388#Method ##
1389
1390# ------------------------------------------------------------------------------
1391
Cary Clarka560c472017-11-27 10:44:06 -05001392#Enum CachingHint
Cary Clark682c58d2018-05-16 07:07:07 -04001393#Line # options for readPixels and scalePixels ##
Cary Clarka560c472017-11-27 10:44:06 -05001394#Code
1395 enum CachingHint {
1396 kAllow_CachingHint,
1397 kDisallow_CachingHint,
1398 };
1399##
1400
Cary Clarkac47b882018-01-11 10:35:44 -05001401CachingHint selects whether Skia may internally cache Bitmaps generated by
1402decoding Image, or by copying Image from GPU to CPU. The default behavior
Cary Clark682c58d2018-05-16 07:07:07 -04001403allows caching Bitmaps.
Cary Clarkac47b882018-01-11 10:35:44 -05001404
1405Choose kDisallow_CachingHint if Image pixels are to be used only once, or
1406if Image pixels reside in a cache outside of Skia, or to reduce memory pressure.
1407
1408Choosing kAllow_CachingHint does not ensure that pixels will be cached.
1409Image pixels may not be cached if memory requirements are too large or
1410pixels are not accessible.
Cary Clarka560c472017-11-27 10:44:06 -05001411
1412#Const kAllow_CachingHint 0
Cary Clark682c58d2018-05-16 07:07:07 -04001413#Line # allows internally caching decoded and copied pixels ##
Cary Clarka560c472017-11-27 10:44:06 -05001414##
1415#Const kDisallow_CachingHint 1
Cary Clark682c58d2018-05-16 07:07:07 -04001416#Line # disallows internally caching decoded and copied pixels ##
Cary Clarka560c472017-11-27 10:44:06 -05001417##
1418
Cary Clarkac47b882018-01-11 10:35:44 -05001419#NoExample
Cary Clarka560c472017-11-27 10:44:06 -05001420##
1421
Cary Clarkac47b882018-01-11 10:35:44 -05001422#SeeAlso readPixels scalePixels
Cary Clarka560c472017-11-27 10:44:06 -05001423
1424#Enum ##
1425
1426# ------------------------------------------------------------------------------
1427
1428#Method bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes,
1429 int srcX, int srcY, CachingHint cachingHint = kAllow_CachingHint) const
Cary Clark78de7512018-02-07 07:27:09 -05001430#In Pixels
Cary Clark4855f782018-02-06 09:41:53 -05001431#Line # copies and converts pixels ##
Cary Clarka560c472017-11-27 10:44:06 -05001432
Cary Clarkac47b882018-01-11 10:35:44 -05001433Copies Rect of pixels from Image to dstPixels. Copy starts at offset (srcX, srcY),
Cary Clark682c58d2018-05-16 07:07:07 -04001434and does not exceed Image (width(), height()).
Cary Clarkac47b882018-01-11 10:35:44 -05001435
1436dstInfo specifies width, height, Color_Type, Alpha_Type, and Color_Space of
1437destination. dstRowBytes specifics the gap from one destination row to the next.
1438Returns true if pixels are copied. Returns false if:
1439#List
1440# dstInfo.addr() equals nullptr ##
1441# dstRowBytes is less than dstInfo.minRowBytes ##
1442# Pixel_Ref is nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -05001443##
1444
Cary Clarkac47b882018-01-11 10:35:44 -05001445Pixels are copied only if pixel conversion is possible. If Image Color_Type is
1446kGray_8_SkColorType, or kAlpha_8_SkColorType; dstInfo.colorType must match.
1447If Image Color_Type is kGray_8_SkColorType, dstInfo.colorSpace must match.
1448If Image Alpha_Type is kOpaque_SkAlphaType, dstInfo.alphaType must
1449match. If Image Color_Space is nullptr, dstInfo.colorSpace must match. Returns
1450false if pixel conversion is not possible.
Cary Clarka560c472017-11-27 10:44:06 -05001451
Cary Clarkac47b882018-01-11 10:35:44 -05001452srcX and srcY may be negative to copy only top or left of source. Returns
Cary Clark682c58d2018-05-16 07:07:07 -04001453false if width() or height() is zero or negative.
1454Returns false if
Cary Clarkac47b882018-01-11 10:35:44 -05001455#Formula
1456abs(srcX) >= Image width()
1457##
1458, or if
1459#Formula
1460abs(srcY) >= Image height()
1461##
1462.
Cary Clarka560c472017-11-27 10:44:06 -05001463
Cary Clarkac47b882018-01-11 10:35:44 -05001464If cachingHint is kAllow_CachingHint, pixels may be retained locally.
1465If cachingHint is kDisallow_CachingHint, pixels are not added to the local cache.
1466
1467#Param dstInfo destination width, height, Color_Type, Alpha_Type, Color_Space ##
1468#Param dstPixels destination pixel storage ##
1469#Param dstRowBytes destination row length ##
1470#Param srcX column index whose absolute value is less than width() ##
1471#Param srcY row index whose absolute value is less than height() ##
1472#Param cachingHint one of: kAllow_CachingHint, kDisallow_CachingHint ##
1473
1474#Return true if pixels are copied to dstPixels ##
Cary Clarka560c472017-11-27 10:44:06 -05001475
1476#Example
Cary Clarkac47b882018-01-11 10:35:44 -05001477#Image 3
1478 canvas->scale(.5f, .5f);
1479 const int width = 32;
1480 const int height = 32;
1481 std::vector<int32_t> dstPixels;
1482 dstPixels.resize(height * width * 4);
1483 SkImageInfo info = SkImageInfo::MakeN32Premul(width, height);
1484 for (int y = 0; y < 512; y += height ) {
1485 for (int x = 0; x < 512; x += width ) {
1486 if (image->readPixels(info, &dstPixels.front(), width * 4, x, y)) {
1487 SkPixmap dstPixmap(info, &dstPixels.front(), width * 4);
1488 SkBitmap bitmap;
1489 bitmap.installPixels(dstPixmap);
1490 canvas->drawBitmap(bitmap, 0, 0);
1491 }
1492 canvas->translate(48, 0);
1493 }
1494 canvas->translate(-16 * 48, 48);
1495 }
Cary Clarka560c472017-11-27 10:44:06 -05001496##
1497
Cary Clarkac47b882018-01-11 10:35:44 -05001498#SeeAlso scalePixels SkBitmap::readPixels SkPixmap::readPixels SkCanvas::readPixels SkSurface::readPixels
Cary Clarka560c472017-11-27 10:44:06 -05001499
1500#Method ##
1501
1502# ------------------------------------------------------------------------------
1503
1504#Method bool readPixels(const SkPixmap& dst, int srcX, int srcY,
1505 CachingHint cachingHint = kAllow_CachingHint) const
1506
Cary Clarkac47b882018-01-11 10:35:44 -05001507Copies a Rect of pixels from Image to dst. Copy starts at (srcX, srcY), and
Cary Clark682c58d2018-05-16 07:07:07 -04001508does not exceed Image (width(), height()).
Cary Clarka560c472017-11-27 10:44:06 -05001509
Cary Clarkac47b882018-01-11 10:35:44 -05001510dst specifies width, height, Color_Type, Alpha_Type, Color_Space, pixel storage,
1511and row bytes of destination. dst.rowBytes specifics the gap from one destination
1512row to the next. Returns true if pixels are copied. Returns false if:
1513#List
1514# dst pixel storage equals nullptr ##
1515# dst.rowBytes is less than SkImageInfo::minRowBytes ##
1516# Pixel_Ref is nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -05001517##
1518
Cary Clarkac47b882018-01-11 10:35:44 -05001519Pixels are copied only if pixel conversion is possible. If Image Color_Type is
1520kGray_8_SkColorType, or kAlpha_8_SkColorType; dst.colorType must match.
1521If Image Color_Type is kGray_8_SkColorType, dst.colorSpace must match.
1522If Image Alpha_Type is kOpaque_SkAlphaType, dst.alphaType must
1523match. If Image Color_Space is nullptr, dst.colorSpace must match. Returns
1524false if pixel conversion is not possible.
Cary Clark682c58d2018-05-16 07:07:07 -04001525
Cary Clarkac47b882018-01-11 10:35:44 -05001526srcX and srcY may be negative to copy only top or left of source. Returns
Cary Clark682c58d2018-05-16 07:07:07 -04001527false if width() or height() is zero or negative.
1528Returns false if
Cary Clarkac47b882018-01-11 10:35:44 -05001529#Formula
1530abs(srcX) >= Image width()
1531##
1532, or if
1533#Formula
1534abs(srcY) >= Image height()
1535##
1536.
1537
1538If cachingHint is kAllow_CachingHint, pixels may be retained locally.
1539If cachingHint is kDisallow_CachingHint, pixels are not added to the local cache.
1540
1541#Param dst destination Pixmap: Image_Info, pixels, row bytes ##
1542#Param srcX column index whose absolute value is less than width() ##
1543#Param srcY row index whose absolute value is less than height() ##
1544#Param cachingHint one of: kAllow_CachingHint, kDisallow_CachingHint ##
1545
1546#Return true if pixels are copied to dst ##
1547
1548#Example
1549#Image 3
1550 std::vector<int32_t> srcPixels;
1551 int rowBytes = image->width() * 4;
1552 int quarterWidth = image->width() / 4;
1553 int quarterHeight = image->height() / 4;
1554 srcPixels.resize(image->height() * rowBytes);
1555 for (int y = 0; y < 4; ++y) {
1556 for (int x = 0; x < 4; ++x) {
1557 SkPixmap pixmap(SkImageInfo::MakeN32Premul(quarterWidth, quarterHeight),
1558 &srcPixels.front() + x * image->height() * quarterWidth +
1559 y * quarterWidth, rowBytes);
1560 image->readPixels(pixmap, x * quarterWidth, y * quarterHeight);
1561 }
1562 }
1563 canvas->scale(.5f, .5f);
1564 SkBitmap bitmap;
1565 bitmap.installPixels(SkImageInfo::MakeN32Premul(image->width(), image->height()),
1566 &srcPixels.front(), rowBytes);
1567 canvas->drawBitmap(bitmap, 0, 0);
1568##
1569
1570#SeeAlso scalePixels SkBitmap::readPixels SkPixmap::readPixels SkCanvas::readPixels SkSurface::readPixels
Cary Clarka560c472017-11-27 10:44:06 -05001571
1572#Method ##
1573
1574# ------------------------------------------------------------------------------
1575
1576#Method bool scalePixels(const SkPixmap& dst, SkFilterQuality filterQuality,
1577 CachingHint cachingHint = kAllow_CachingHint) const
Cary Clark78de7512018-02-07 07:27:09 -05001578#In Pixels
Cary Clark4855f782018-02-06 09:41:53 -05001579#Line # scales and converts one Image to another ##
Cary Clarka560c472017-11-27 10:44:06 -05001580
Cary Clarkac47b882018-01-11 10:35:44 -05001581Copies Image to dst, scaling pixels to fit dst.width() and dst.height(), and
1582converting pixels to match dst.colorType and dst.alphaType. Returns true if
1583pixels are copied. Returns false if dst.addr() is nullptr, or dst.rowBytes is
1584less than dst SkImageInfo::minRowBytes.
Cary Clarka560c472017-11-27 10:44:06 -05001585
Cary Clarkac47b882018-01-11 10:35:44 -05001586Pixels are copied only if pixel conversion is possible. If Image Color_Type is
1587kGray_8_SkColorType, or kAlpha_8_SkColorType; dst.colorType must match.
1588If Image Color_Type is kGray_8_SkColorType, dst.colorSpace must match.
1589If Image Alpha_Type is kOpaque_SkAlphaType, dst.alphaType must
1590match. If Image Color_Space is nullptr, dst.colorSpace must match. Returns
1591false if pixel conversion is not possible.
Cary Clarka560c472017-11-27 10:44:06 -05001592
Cary Clarkac47b882018-01-11 10:35:44 -05001593Scales the image, with filterQuality, to match dst.width() and dst.height().
1594filterQuality kNone_SkFilterQuality is fastest, typically implemented with
1595Filter_Quality_Nearest_Neighbor. kLow_SkFilterQuality is typically implemented with
1596Filter_Quality_Bilerp. kMedium_SkFilterQuality is typically implemented with
1597Filter_Quality_Bilerp, and Filter_Quality_MipMap when size is reduced.
1598kHigh_SkFilterQuality is slowest, typically implemented with Filter_Quality_BiCubic.
1599
1600If cachingHint is kAllow_CachingHint, pixels may be retained locally.
1601If cachingHint is kDisallow_CachingHint, pixels are not added to the local cache.
1602
1603#Param dst destination Pixmap: Image_Info, pixels, row bytes ##
1604#Param filterQuality one of: kNone_SkFilterQuality, kLow_SkFilterQuality,
1605 kMedium_SkFilterQuality, kHigh_SkFilterQuality
1606##
1607#Param cachingHint one of: kAllow_CachingHint, kDisallow_CachingHint ##
1608
1609#Return true if pixels are scaled to fit dst ##
Cary Clarka560c472017-11-27 10:44:06 -05001610
1611#Example
Cary Clarkac47b882018-01-11 10:35:44 -05001612#Image 3
1613#Height 128
1614 std::vector<int32_t> srcPixels;
1615 int quarterWidth = image->width() / 16;
1616 int rowBytes = quarterWidth * 4;
1617 int quarterHeight = image->height() / 16;
1618 srcPixels.resize(quarterHeight * rowBytes);
1619 SkPixmap pixmap(SkImageInfo::MakeN32Premul(quarterWidth, quarterHeight),
1620 &srcPixels.front(), rowBytes);
1621 canvas->scale(4, 4);
1622 SkFilterQuality qualities[] = { kNone_SkFilterQuality, kLow_SkFilterQuality,
1623 kMedium_SkFilterQuality, kHigh_SkFilterQuality };
1624 for (unsigned index = 0; index < SK_ARRAY_COUNT(qualities); ++index) {
1625 image->scalePixels(pixmap, qualities[index]);
1626 sk_sp<SkImage> filtered = SkImage::MakeFromRaster(pixmap, nullptr, nullptr);
1627 canvas->drawImage(filtered, 16 * index, 0);
1628 }
Cary Clarka560c472017-11-27 10:44:06 -05001629##
1630
Cary Clarkac47b882018-01-11 10:35:44 -05001631#SeeAlso SkCanvas::drawImage readPixels SkPixmap::scalePixels
Cary Clarka560c472017-11-27 10:44:06 -05001632
1633#Method ##
1634
1635# ------------------------------------------------------------------------------
1636
1637#Method sk_sp<SkData> encodeToData(SkEncodedImageFormat encodedImageFormat, int quality) const
Cary Clark78de7512018-02-07 07:27:09 -05001638#In Utility
Cary Clark4855f782018-02-06 09:41:53 -05001639#Line # returns encoded Image as SkData ##
Cary Clark682c58d2018-05-16 07:07:07 -04001640Encodes Image pixels, returning result as SkData.
Cary Clark2f466242017-12-11 16:03:17 -05001641
Cary Clarkac47b882018-01-11 10:35:44 -05001642Returns nullptr if encoding fails, or if encodedImageFormat is not supported.
Cary Clarka560c472017-11-27 10:44:06 -05001643
Cary Clarkac47b882018-01-11 10:35:44 -05001644Image encoding in a format requires both building with one or more of:
1645SK_HAS_JPEG_LIBRARY, SK_HAS_PNG_LIBRARY, SK_HAS_WEBP_LIBRARY; and platform support
1646for the encoded format.
1647
1648If SK_BUILD_FOR_MAC or SK_BUILD_FOR_IOS is defined, encodedImageFormat can
1649additionally be one of: SkEncodedImageFormat::kICO, SkEncodedImageFormat::kBMP,
1650SkEncodedImageFormat::kGIF.
1651
1652quality is a platform and format specific metric trading off size and encoding
1653error. When used, quality equaling 100 encodes with the least error. quality may
1654be ignored by the encoder.
1655
1656#Param encodedImageFormat one of: SkEncodedImageFormat::kJPEG, SkEncodedImageFormat::kPNG,
1657 SkEncodedImageFormat::kWEBP
1658 ##
1659#Param quality encoder specific metric with 100 equaling best ##
Cary Clarka560c472017-11-27 10:44:06 -05001660
Cary Clark2f466242017-12-11 16:03:17 -05001661#Return encoded Image, or nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -05001662
1663#Example
Cary Clarkac47b882018-01-11 10:35:44 -05001664#Image 3
1665 canvas->scale(4, 4);
1666 SkIRect subset = {0, 0, 16, 64};
1667 int x = 0;
1668 for (int quality : { 0, 10, 50, 100 } ) {
1669 sk_sp<SkData> data(image->encodeToData(SkEncodedImageFormat::kJPEG, quality));
1670 sk_sp<SkImage> filtered = SkImage::MakeFromEncoded(data, &subset);
1671 canvas->drawImage(filtered, x, 0);
1672 x += 16;
1673 }
Cary Clarka560c472017-11-27 10:44:06 -05001674##
1675
Cary Clarkac47b882018-01-11 10:35:44 -05001676#SeeAlso refEncodedData MakeFromEncoded
Cary Clarka560c472017-11-27 10:44:06 -05001677
1678#Method ##
1679
1680# ------------------------------------------------------------------------------
1681
Cary Clark61ca7c52018-01-02 11:34:14 -05001682#Method sk_sp<SkData> encodeToData() const
Cary Clarka560c472017-11-27 10:44:06 -05001683
Cary Clarkac47b882018-01-11 10:35:44 -05001684Encodes Image pixels, returning result as SkData. Returns existing encoded data
1685if present; otherwise, Image is encoded with SkEncodedImageFormat::kPNG. Skia
1686must be built with SK_HAS_PNG_LIBRARY to encode Image.
Cary Clarka560c472017-11-27 10:44:06 -05001687
Cary Clark682c58d2018-05-16 07:07:07 -04001688Returns nullptr if existing encoded data is missing or invalid, and
Cary Clarka560c472017-11-27 10:44:06 -05001689encoding fails.
1690
Cary Clarkac47b882018-01-11 10:35:44 -05001691#Return encoded Image, or nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -05001692
1693#Example
Cary Clarkac47b882018-01-11 10:35:44 -05001694#Image 3
1695 canvas->scale(4, 4);
1696 SkIRect subset = {136, 32, 200, 96};
1697 sk_sp<SkData> data(image->encodeToData());
1698 sk_sp<SkImage> eye = SkImage::MakeFromEncoded(data, &subset);
1699 canvas->drawImage(eye, 0, 0);
Cary Clarka560c472017-11-27 10:44:06 -05001700##
1701
Cary Clarkac47b882018-01-11 10:35:44 -05001702#SeeAlso refEncodedData MakeFromEncoded
Cary Clarka560c472017-11-27 10:44:06 -05001703
1704#Method ##
1705
1706# ------------------------------------------------------------------------------
1707
1708#Method sk_sp<SkData> refEncodedData() const
Cary Clark78de7512018-02-07 07:27:09 -05001709#In Utility
Cary Clark4855f782018-02-06 09:41:53 -05001710#Line # returns Image encoded in SkData if present ##
Cary Clarkac47b882018-01-11 10:35:44 -05001711Returns encoded Image pixels as SkData, if Image was created from supported
1712encoded stream format. Platform support for formats vary and may require building
1713with one or more of: SK_HAS_JPEG_LIBRARY, SK_HAS_PNG_LIBRARY, SK_HAS_WEBP_LIBRARY.
Cary Clarka560c472017-11-27 10:44:06 -05001714
Cary Clarkac47b882018-01-11 10:35:44 -05001715Returns nullptr if Image contents are not encoded.
Cary Clarka560c472017-11-27 10:44:06 -05001716
Cary Clarkac47b882018-01-11 10:35:44 -05001717#Return encoded Image, or nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -05001718
1719#Example
Cary Clarkac47b882018-01-11 10:35:44 -05001720#Image 3
1721#Platform gpu
1722 struct {
1723 const char* name;
1724 sk_sp<SkImage> image;
1725 } tests[] = { { "image", image }, { "bitmap", SkImage::MakeFromBitmap(source) },
1726 { "texture", SkImage::MakeFromTexture(canvas->getGrContext(), backEndTexture,
Cary Clark471b6fe2018-03-21 08:52:41 -04001727 kTopLeft_GrSurfaceOrigin, kN32_SkColorType, kOpaque_SkAlphaType,
1728 nullptr) } };
Cary Clarkac47b882018-01-11 10:35:44 -05001729 SkString string;
1730 SkPaint paint;
1731 for (const auto& test : tests ) {
1732 if (!test.image) {
1733 string.printf("no %s", test.name);
1734 } else {
1735 string.printf("%s" "encoded %s", test.image->refEncodedData() ? "" : "no ", test.name);
1736 }
1737 canvas->drawString(string, 10, 20, paint);
1738 canvas->translate(0, 20);
1739 }
Cary Clarka560c472017-11-27 10:44:06 -05001740##
1741
Cary Clarkac47b882018-01-11 10:35:44 -05001742#SeeAlso encodeToData MakeFromEncoded
Cary Clarka560c472017-11-27 10:44:06 -05001743
1744#Method ##
1745
1746# ------------------------------------------------------------------------------
Cary Clark4855f782018-02-06 09:41:53 -05001747#Subtopic Utility
1748#Populate
1749#Line # rarely called management functions ##
1750##
Cary Clarka560c472017-11-27 10:44:06 -05001751
1752#Method const char* toString(SkString* string) const
Cary Clark4855f782018-02-06 09:41:53 -05001753#In Utility
1754#Line # converts Image to machine readable form ##
Cary Clarkac47b882018-01-11 10:35:44 -05001755Appends Image description to string, including unique ID, width, height, and
1756whether the image is opaque.
Cary Clarka560c472017-11-27 10:44:06 -05001757
Cary Clarkac47b882018-01-11 10:35:44 -05001758#Param string storage for description; existing content is preserved ##
1759
1760#Return string appended with Image description ##
Cary Clarka560c472017-11-27 10:44:06 -05001761
1762#Example
Cary Clarkac47b882018-01-11 10:35:44 -05001763#Image 4
1764 struct {
1765 const char* name;
1766 sk_sp<SkImage> image;
1767 } tests[] = { { "image", image }, { "bitmap", SkImage::MakeFromBitmap(source) },
1768 { "texture", SkImage::MakeFromTexture(canvas->getGrContext(), backEndTexture,
Cary Clark471b6fe2018-03-21 08:52:41 -04001769 kTopLeft_GrSurfaceOrigin, kN32_SkColorType, kOpaque_SkAlphaType,
1770 nullptr) } };
Cary Clarkac47b882018-01-11 10:35:44 -05001771 SkString string;
1772 SkPaint paint;
1773 for (const auto& test : tests ) {
1774 string.printf("%s: ", test.name);
1775 test.image ? (void) test.image->toString(&string) : string.append("no image");
1776 canvas->drawString(string, 10, 20, paint);
1777 canvas->translate(0, 20);
1778 }
Cary Clarka560c472017-11-27 10:44:06 -05001779##
1780
Cary Clarkac47b882018-01-11 10:35:44 -05001781#SeeAlso SkPaint::toString
Cary Clarka560c472017-11-27 10:44:06 -05001782
1783#Method ##
1784
1785# ------------------------------------------------------------------------------
1786
1787#Method sk_sp<SkImage> makeSubset(const SkIRect& subset) const
Cary Clark4855f782018-02-06 09:41:53 -05001788#In Constructor
1789#Line # creates Image containing part of original ##
Cary Clarkac47b882018-01-11 10:35:44 -05001790Returns subset of Image. subset must be fully contained by Image dimensions().
1791The implementation may share pixels, or may copy them.
Cary Clarka560c472017-11-27 10:44:06 -05001792
Cary Clarkac47b882018-01-11 10:35:44 -05001793Returns nullptr if subset is empty, or subset is not contained by bounds, or
1794pixels in Image could not be read or copied.
Cary Clarka560c472017-11-27 10:44:06 -05001795
Cary Clarkac47b882018-01-11 10:35:44 -05001796#Param subset bounds of returned Image ##
1797
1798#Return partial or full Image, or nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -05001799
1800#Example
Cary Clarkac47b882018-01-11 10:35:44 -05001801#Image 3
1802 canvas->scale(.5f, .5f);
1803 const int width = 32;
1804 const int height = 32;
1805 for (int y = 0; y < 512; y += height ) {
1806 for (int x = 0; x < 512; x += width ) {
1807 sk_sp<SkImage> subset(image->makeSubset({x, y, x + width, y + height}));
1808 canvas->drawImage(subset, x * 3 / 2, y * 3 / 2);
1809 }
1810 }
Cary Clarka560c472017-11-27 10:44:06 -05001811##
1812
Cary Clarkac47b882018-01-11 10:35:44 -05001813#SeeAlso MakeFromEncoded
Cary Clarka560c472017-11-27 10:44:06 -05001814
1815#Method ##
1816
1817# ------------------------------------------------------------------------------
1818
1819#Method sk_sp<SkImage> makeTextureImage(GrContext* context, SkColorSpace* dstColorSpace) const
Cary Clark4855f782018-02-06 09:41:53 -05001820#In Constructor
1821#Line # creates Image matching Color_Space if possible ##
Cary Clarkac47b882018-01-11 10:35:44 -05001822Returns Image backed by GPU_Texture associated with context. Returned Image is
1823compatible with Surface created with dstColorSpace. Returns original
1824Image if context and dstColorSpace match.
1825
1826Returns nullptr if context is nullptr, or if Image was created with another
1827GrContext.
Cary Clarka560c472017-11-27 10:44:06 -05001828
Cary Clark61ca7c52018-01-02 11:34:14 -05001829#Param context GPU_Context ##
Cary Clarkac47b882018-01-11 10:35:44 -05001830#Param dstColorSpace range of colors of matching Surface on GPU ##
Cary Clarka560c472017-11-27 10:44:06 -05001831
Cary Clarkac47b882018-01-11 10:35:44 -05001832#Return created Image, or nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -05001833
1834#Example
Cary Clarkac47b882018-01-11 10:35:44 -05001835#Platform gpu
1836#Image 5
1837 auto drawImage = [=](sk_sp<SkImage> image, GrContext* context, const char* label) -> void {
1838 if (nullptr == image || nullptr == context) {
1839 return;
1840 }
1841 SkPaint paint;
1842 paint.setAntiAlias(true);
1843 paint.setTextAlign(SkPaint::kCenter_Align);
1844 sk_sp<SkImage> texture(image->makeTextureImage(context, nullptr));
1845 canvas->drawImage(texture, 0, 0);
1846 canvas->drawString(label, texture->width() / 2, texture->height() / 4, paint);
1847 };
1848 sk_sp<SkImage> bitmapImage(SkImage::MakeFromBitmap(source));
1849 GrContext* context = canvas->getGrContext();
1850 sk_sp<SkImage> textureImage(SkImage::MakeFromTexture(context, backEndTexture,
Cary Clark471b6fe2018-03-21 08:52:41 -04001851 kTopLeft_GrSurfaceOrigin, kN32_SkColorType, kOpaque_SkAlphaType,
1852 nullptr));
Cary Clarkac47b882018-01-11 10:35:44 -05001853 drawImage(image, context, "image");
1854 canvas->translate(image->width(), 0);
1855 drawImage(bitmapImage, context, "source");
1856 canvas->translate(-image->width(), image->height());
1857 drawImage(textureImage, context, "backEndTexture");
Cary Clarka560c472017-11-27 10:44:06 -05001858##
1859
Cary Clarkac47b882018-01-11 10:35:44 -05001860#SeeAlso MakeFromTexture
Cary Clarka560c472017-11-27 10:44:06 -05001861
1862#Method ##
1863
1864# ------------------------------------------------------------------------------
1865
1866#Method sk_sp<SkImage> makeNonTextureImage() const
Cary Clark4855f782018-02-06 09:41:53 -05001867#In Constructor
1868#Line # creates Image without dependency on GPU_Texture ##
Cary Clarkac47b882018-01-11 10:35:44 -05001869Returns Raster_Image or Lazy_Image. Copies Image backed by GPU_Texture into
Cary Clark4855f782018-02-06 09:41:53 -05001870CPU memory if needed. Returns original Image if decoded in Raster_Bitmap,
Cary Clarkac47b882018-01-11 10:35:44 -05001871or if encoded in a stream.
Cary Clark61ca7c52018-01-02 11:34:14 -05001872
Cary Clarkac47b882018-01-11 10:35:44 -05001873Returns nullptr if backed by GPU_Texture and copy fails.
1874
1875#Return Raster_Image, Lazy_Image, or nullptr ##
Cary Clark61ca7c52018-01-02 11:34:14 -05001876
1877#Example
Cary Clarkac47b882018-01-11 10:35:44 -05001878#Image 5
1879#Platform gpu
1880 auto drawImage = [=](sk_sp<SkImage> image, const char* label) -> void {
1881 if (nullptr == image) {
1882 return;
1883 }
1884 SkPaint paint;
1885 paint.setAntiAlias(true);
1886 paint.setTextAlign(SkPaint::kCenter_Align);
1887 sk_sp<SkImage> nonTexture(image->makeNonTextureImage());
1888 canvas->drawImage(nonTexture, 0, 0);
1889 canvas->drawString(label, nonTexture->width() / 2, nonTexture->height() / 4, paint);
1890 };
1891 sk_sp<SkImage> bitmapImage(SkImage::MakeFromBitmap(source));
1892 sk_sp<SkImage> textureImage(SkImage::MakeFromTexture(canvas->getGrContext(), backEndTexture,
Cary Clark471b6fe2018-03-21 08:52:41 -04001893 kTopLeft_GrSurfaceOrigin, kN32_SkColorType, kOpaque_SkAlphaType,
1894 nullptr));
Cary Clarkac47b882018-01-11 10:35:44 -05001895 drawImage(image, "image");
1896 canvas->translate(image->width(), 0);
1897 drawImage(bitmapImage, "source");
1898 canvas->translate(-image->width(), image->height());
1899 drawImage(textureImage, "backEndTexture");
Cary Clark61ca7c52018-01-02 11:34:14 -05001900##
1901
Cary Clark56356312018-02-08 14:45:18 -05001902#SeeAlso makeTextureImage makeRasterImage MakeBackendTextureFromSkImage
Cary Clark61ca7c52018-01-02 11:34:14 -05001903
1904#Method ##
1905
1906# ------------------------------------------------------------------------------
1907
1908#Method sk_sp<SkImage> makeRasterImage() const
Cary Clark4855f782018-02-06 09:41:53 -05001909#In Constructor
1910#Line # creates Image compatible with Raster_Surface if possible ##
Cary Clarkac47b882018-01-11 10:35:44 -05001911Returns Raster_Image. Copies Image backed by GPU_Texture into CPU memory,
Cary Clark4855f782018-02-06 09:41:53 -05001912or decodes Image from Lazy_Image. Returns original Image if decoded in
Cary Clarkac47b882018-01-11 10:35:44 -05001913Raster_Bitmap.
Cary Clarka560c472017-11-27 10:44:06 -05001914
Cary Clarkac47b882018-01-11 10:35:44 -05001915Returns nullptr if copy, decode, or pixel read fails.
Cary Clarka560c472017-11-27 10:44:06 -05001916
Cary Clarkac47b882018-01-11 10:35:44 -05001917#Return Raster_Image, or nullptr ##
1918
Cary Clark4855f782018-02-06 09:41:53 -05001919#Bug 7479
Cary Clarka560c472017-11-27 10:44:06 -05001920#Example
Cary Clarkac47b882018-01-11 10:35:44 -05001921#Image 5
1922#Platform gpu
1923 auto drawImage = [=](sk_sp<SkImage> image, const char* label) -> void {
1924 if (nullptr == image) {
1925 return;
1926 }
1927 SkPaint paint;
1928 paint.setAntiAlias(true);
1929 paint.setTextAlign(SkPaint::kCenter_Align);
1930 sk_sp<SkImage> raster(image->makeRasterImage());
1931 canvas->drawImage(raster, 0, 0);
1932 canvas->drawString(label, raster->width() / 2, raster->height() / 4, paint);
1933 };
1934 sk_sp<SkImage> bitmapImage(SkImage::MakeFromBitmap(source));
1935 sk_sp<SkImage> textureImage(SkImage::MakeFromTexture(canvas->getGrContext(), backEndTexture,
Cary Clark471b6fe2018-03-21 08:52:41 -04001936 kTopLeft_GrSurfaceOrigin, kN32_SkColorType, kOpaque_SkAlphaType,
1937 nullptr));
Cary Clarkac47b882018-01-11 10:35:44 -05001938 drawImage(image, "image");
1939 canvas->translate(image->width(), 0);
1940 drawImage(bitmapImage, "source");
1941 canvas->translate(-image->width(), image->height());
1942 drawImage(textureImage, "backEndTexture");
Cary Clarka560c472017-11-27 10:44:06 -05001943##
1944
Cary Clarkac47b882018-01-11 10:35:44 -05001945#SeeAlso isTextureBacked isLazyGenerated MakeFromRaster
Cary Clarka560c472017-11-27 10:44:06 -05001946
1947#Method ##
1948
1949# ------------------------------------------------------------------------------
1950
1951#Method sk_sp<SkImage> makeWithFilter(const SkImageFilter* filter, const SkIRect& subset,
1952 const SkIRect& clipBounds, SkIRect* outSubset,
1953 SkIPoint* offset) const
Cary Clark4855f782018-02-06 09:41:53 -05001954#In Constructor
1955#Line # creates filtered, clipped Image ##
Cary Clarka560c472017-11-27 10:44:06 -05001956
Cary Clarkac47b882018-01-11 10:35:44 -05001957Creates filtered Image. filter processes original Image, potentially changing
1958color, position, and size. subset is the bounds of original Image processed
1959by filter. clipBounds is the expected bounds of the filtered Image. outSubset
1960is required storage for the actual bounds of the filtered Image. offset is
1961required storage for translation of returned Image.
Cary Clarka560c472017-11-27 10:44:06 -05001962
Cary Clarkac47b882018-01-11 10:35:44 -05001963Returns nullptr if Image could not be created. If nullptr is returned, outSubset
1964and offset are undefined.
1965
Cary Clark56356312018-02-08 14:45:18 -05001966Useful for animation of SkImageFilter that varies size from frame to frame.
1967Returned Image is created larger than required by filter so that GPU_Texture
1968can be reused with different sized effects. outSubset describes the valid bounds
1969of GPU_Texture returned. offset translates the returned Image to keep subsequent
1970animation frames aligned with respect to each other.
Cary Clarkac47b882018-01-11 10:35:44 -05001971
1972#Param filter how Image is sampled when transformed ##
Cary Clark56356312018-02-08 14:45:18 -05001973#Param subset bounds of Image processed by filter ##
1974#Param clipBounds expected bounds of filtered Image ##
1975#Param outSubset storage for returned Image bounds ##
1976#Param offset storage for returned Image translation ##
Cary Clarka560c472017-11-27 10:44:06 -05001977
Cary Clarkac47b882018-01-11 10:35:44 -05001978#Return filtered Image, or nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -05001979
1980#Example
Cary Clarkac47b882018-01-11 10:35:44 -05001981#Description
1982In each frame of the animation, filtered Image is drawn in a different location.
1983By translating canvas by returned offset, Image appears stationary.
1984##
1985#Image 5
1986#Platform gpu
1987#Duration 5
1988 sk_sp<SkImageFilter> shadowFilter = SkDropShadowImageFilter::Make(
1989 -10.0f * frame, 5.0f * frame, 3.0f, 3.0f, SK_ColorBLUE,
1990 SkDropShadowImageFilter::kDrawShadowAndForeground_ShadowMode,
1991 nullptr);
1992 sk_sp<SkImageFilter> offsetFilter = SkOffsetImageFilter::Make(40, 40, shadowFilter, nullptr);
1993 SkIRect subset = image->bounds();
1994 SkIRect clipBounds = image->bounds();
1995 clipBounds.outset(60, 60);
1996 SkIRect outSubset;
1997 SkIPoint offset;
1998 sk_sp<SkImage> filtered(image->makeWithFilter(offsetFilter.get(), subset, clipBounds,
1999 &outSubset, &offset));
2000 SkPaint paint;
2001 paint.setAntiAlias(true);
2002 paint.setStyle(SkPaint::kStroke_Style);
2003 canvas->drawLine(0, 0, offset.fX, offset.fY, paint);
2004 canvas->translate(offset.fX, offset.fY);
2005 canvas->drawImage(filtered, 0, 0);
Cary Clark681287e2018-03-16 11:34:15 -04002006 canvas->drawRect(SkRect::Make(outSubset), paint);
Cary Clarka560c472017-11-27 10:44:06 -05002007##
2008
Cary Clark56356312018-02-08 14:45:18 -05002009#SeeAlso makeShader SkPaint::setImageFilter
Cary Clarka560c472017-11-27 10:44:06 -05002010
2011#Method ##
2012
2013# ------------------------------------------------------------------------------
2014
Cary Clarka560c472017-11-27 10:44:06 -05002015#Typedef std::function<void(GrBackendTexture)> BackendTextureReleaseProc
Cary Clark682c58d2018-05-16 07:07:07 -04002016#Line # parameter type for MakeBackendTextureFromSkImage ##
Cary Clarkffb3d682018-05-17 12:17:28 -04002017
2018#Code
2019typedef std::function<void(GrBackendTexture)> BackendTextureReleaseProc;
2020##
2021
Cary Clark682c58d2018-05-16 07:07:07 -04002022Defines a function take one parameter of type
2023GrBackendTexture with no return value.
Cary Clarka560c472017-11-27 10:44:06 -05002024##
2025
2026# ------------------------------------------------------------------------------
2027
2028#Method static bool MakeBackendTextureFromSkImage(GrContext* context,
2029 sk_sp<SkImage> image,
2030 GrBackendTexture* backendTexture,
2031 BackendTextureReleaseProc* backendTextureReleaseProc)
Cary Clark4855f782018-02-06 09:41:53 -05002032#In Constructor
2033#Line # creates GPU_Texture from Image ##
Cary Clarka560c472017-11-27 10:44:06 -05002034
Cary Clark56356312018-02-08 14:45:18 -05002035Creates a GrBackendTexture from the provided SkImage. Returns true and
2036stores result in backendTexture and backendTextureReleaseProc if
2037texture is created; otherwise, returns false and leaves
2038backendTexture and backendTextureReleaseProc unmodified.
Cary Clarka560c472017-11-27 10:44:06 -05002039
Cary Clark56356312018-02-08 14:45:18 -05002040Call backendTextureReleaseProc after deleting backendTexture.
2041backendTextureReleaseProc cleans up auxiliary data related to returned
2042backendTexture. The caller must delete returned backendTexture after use.
Cary Clarka560c472017-11-27 10:44:06 -05002043
Cary Clark56356312018-02-08 14:45:18 -05002044If Image is both texture backed and singly referenced, image is returned in
2045backendTexture without conversion or making a copy. Image is singly referenced
2046if its was transferred solely using std::move().
2047
2048If Image is not texture backed, returns texture with Image contents.
Cary Clarka560c472017-11-27 10:44:06 -05002049
Cary Clark61ca7c52018-01-02 11:34:14 -05002050#Param context GPU_Context ##
Cary Clark56356312018-02-08 14:45:18 -05002051#Param image Image used for texture ##
Cary Clark682c58d2018-05-16 07:07:07 -04002052#Param backendTexture storage for back-end texture ##
Cary Clark56356312018-02-08 14:45:18 -05002053#Param backendTextureReleaseProc storage for clean up function ##
Cary Clarka560c472017-11-27 10:44:06 -05002054
Cary Clark682c58d2018-05-16 07:07:07 -04002055#Return true if back-end texture was created ##
Cary Clarka560c472017-11-27 10:44:06 -05002056
2057#Example
Cary Clark56356312018-02-08 14:45:18 -05002058#Platform gpu
2059#Height 64
2060#Function
Brian Salomon67f85842018-02-09 08:50:22 -05002061static sk_sp<SkImage> create_gpu_image(GrContext* grContext) {
2062 const SkImageInfo info = SkImageInfo::MakeN32(20, 20, kOpaque_SkAlphaType);
2063 auto surface(SkSurface::MakeRenderTarget(grContext, SkBudgeted::kNo, info));
2064 SkCanvas* canvas = surface->getCanvas();
2065 canvas->clear(SK_ColorWHITE);
2066 SkPaint paint;
2067 paint.setColor(SK_ColorBLACK);
2068 canvas->drawRect(SkRect::MakeXYWH(5, 5, 10, 10), paint);
2069 return surface->makeImageSnapshot();
2070}
2071##
2072
Cary Clark682c58d2018-05-16 07:07:07 -04002073void draw(SkCanvas* canvas) {
Brian Salomon67f85842018-02-09 08:50:22 -05002074 GrContext* grContext = canvas->getGrContext();
2075 if (!grContext) {
2076 return;
2077 }
2078 sk_sp<SkImage> backEndImage = create_gpu_image(grContext);
2079 canvas->drawImage(backEndImage, 0, 0);
2080 GrBackendTexture texture;
2081 SkImage::BackendTextureReleaseProc proc;
2082 if (!SkImage::MakeBackendTextureFromSkImage(grContext, std::move(backEndImage),
2083 &texture, &proc)) {
2084 return;
2085 }
2086 sk_sp<SkImage> i2 = SkImage::MakeFromTexture(grContext, texture, kTopLeft_GrSurfaceOrigin,
2087 kN32_SkColorType, kOpaque_SkAlphaType, nullptr);
2088 canvas->drawImage(i2, 30, 30);
Cary Clark56356312018-02-08 14:45:18 -05002089}
Cary Clarka560c472017-11-27 10:44:06 -05002090##
2091
Cary Clark56356312018-02-08 14:45:18 -05002092#SeeAlso MakeFromTexture makeTextureImage
Cary Clarka560c472017-11-27 10:44:06 -05002093
2094#Method ##
2095
2096# ------------------------------------------------------------------------------
2097
2098#Enum LegacyBitmapMode
Cary Clark56356312018-02-08 14:45:18 -05002099#Deprecated soon
Cary Clarka560c472017-11-27 10:44:06 -05002100#Code
2101 enum LegacyBitmapMode {
2102 kRO_LegacyBitmapMode,
Cary Clarka560c472017-11-27 10:44:06 -05002103 };
2104##
2105
Cary Clarka560c472017-11-27 10:44:06 -05002106#Const kRO_LegacyBitmapMode 0
Cary Clark682c58d2018-05-16 07:07:07 -04002107#Line # returned bitmap is read-only and immutable ##
Cary Clarka560c472017-11-27 10:44:06 -05002108##
Cary Clarka560c472017-11-27 10:44:06 -05002109
2110#Enum ##
2111
2112# ------------------------------------------------------------------------------
2113
Cary Clark56356312018-02-08 14:45:18 -05002114#Method bool asLegacyBitmap(SkBitmap* bitmap, LegacyBitmapMode legacyBitmapMode = kRO_LegacyBitmapMode) const
Cary Clark4855f782018-02-06 09:41:53 -05002115#In Constructor
2116#Line # returns as Raster_Bitmap ##
Cary Clarkac47b882018-01-11 10:35:44 -05002117Creates raster Bitmap with same pixels as Image. If legacyBitmapMode is
2118kRO_LegacyBitmapMode, returned bitmap is read-only and immutable.
2119Returns true if Bitmap is stored in bitmap. Returns false and resets bitmap if
2120Bitmap write did not succeed.
Cary Clarka560c472017-11-27 10:44:06 -05002121
Cary Clark3cd22cc2017-12-01 11:49:58 -05002122#Param bitmap storage for legacy Bitmap ##
Cary Clark56356312018-02-08 14:45:18 -05002123#Param legacyBitmapMode to be deprecated ##
Cary Clarka560c472017-11-27 10:44:06 -05002124
Cary Clark3cd22cc2017-12-01 11:49:58 -05002125#Return true if Bitmap was created ##
Cary Clarka560c472017-11-27 10:44:06 -05002126
2127#Example
Cary Clark56356312018-02-08 14:45:18 -05002128#Image 4
2129#Platform gpu
Brian Salomon67f85842018-02-09 08:50:22 -05002130 SkBitmap bitImage;
2131 if (image->asLegacyBitmap(&bitImage, SkImage::kRO_LegacyBitmapMode)) {
2132 canvas->drawBitmap(bitImage, 0, 0);
2133 }
2134 GrContext* grContext = canvas->getGrContext();
2135 if (!grContext) {
2136 return;
2137 }
2138 sk_sp<SkImage> textureImage(SkImage::MakeFromTexture(grContext, backEndTexture,
Cary Clark471b6fe2018-03-21 08:52:41 -04002139 kTopLeft_GrSurfaceOrigin, kN32_SkColorType, kOpaque_SkAlphaType,
2140 nullptr));
Brian Salomon67f85842018-02-09 08:50:22 -05002141 canvas->drawImage(textureImage, 45, 45);
2142 if (textureImage->asLegacyBitmap(&bitImage, SkImage::kRO_LegacyBitmapMode)) {
2143 canvas->drawBitmap(bitImage, 90, 90);
2144 }
Cary Clarka560c472017-11-27 10:44:06 -05002145##
2146
Cary Clark56356312018-02-08 14:45:18 -05002147#SeeAlso MakeRasterData makeRasterImage makeNonTextureImage
Cary Clarka560c472017-11-27 10:44:06 -05002148
2149#Method ##
2150
2151# ------------------------------------------------------------------------------
2152
2153#Method bool isLazyGenerated() const
Cary Clark4855f782018-02-06 09:41:53 -05002154#In Property
2155#Line # returns if Image is created as needed ##
Cary Clarka560c472017-11-27 10:44:06 -05002156Returns true if Image is backed by an image-generator or other service that creates
2157and caches its pixels or texture on-demand.
2158
Cary Clark2f466242017-12-11 16:03:17 -05002159#Return true if Image is created as needed ##
Cary Clarka560c472017-11-27 10:44:06 -05002160
2161#Example
Cary Clark2f466242017-12-11 16:03:17 -05002162#Height 80
2163#Function
2164class TestImageGenerator : public SkImageGenerator {
2165public:
2166 TestImageGenerator() : SkImageGenerator(SkImageInfo::MakeN32Premul(10, 10)) {}
2167 ~TestImageGenerator() override {}
2168protected:
2169 bool onGetPixels(const SkImageInfo& info, void* pixelPtr, size_t rowBytes,
2170 const Options& options) override {
2171 SkPMColor* pixels = static_cast<SkPMColor*>(pixelPtr);
2172 for (int y = 0; y < info.height(); ++y) {
2173 for (int x = 0; x < info.width(); ++x) {
2174 pixels[y * info.width() + x] = 0xff223344 + y * 0x000C0811;
2175 }
2176 }
2177 return true;
2178 }
2179};
2180##
2181void draw(SkCanvas* canvas) {
2182 auto gen = std::unique_ptr<TestImageGenerator>(new TestImageGenerator());
2183 sk_sp<SkImage> image(SkImage::MakeFromGenerator(std::move(gen)));
2184 SkString lazy(image->isLazyGenerated() ? "is lazy" : "not lazy");
2185 canvas->scale(8, 8);
2186 canvas->drawImage(image, 0, 0, nullptr);
2187 SkPaint paint;
2188 paint.setTextSize(4);
2189 canvas->drawString(lazy, 2, 5, paint);
2190}
Cary Clarka560c472017-11-27 10:44:06 -05002191##
2192
Cary Clarkf5404bb2018-01-05 12:10:09 -05002193#Example
2194#Image 5
2195#Platform gpu
2196void draw(SkCanvas* canvas) {
2197 auto drawImage = [=](sk_sp<SkImage> image, const char* label) -> void {
2198 if (nullptr == image) {
2199 return;
2200 }
2201 SkPaint paint;
2202 paint.setAntiAlias(true);
2203 paint.setTextAlign(SkPaint::kCenter_Align);
2204 canvas->drawImage(image, 0, 0);
2205 canvas->drawString(label, image->width() / 2, image->height() / 4, paint);
2206 canvas->drawString(
2207 image->isLazyGenerated() ? "is lazily generated" : "not lazily generated",
2208 image->width() / 2, image->height() * 3 / 4, paint);
2209 };
2210 sk_sp<SkImage> bitmapImage(SkImage::MakeFromBitmap(source));
2211 sk_sp<SkImage> textureImage(SkImage::MakeFromTexture(canvas->getGrContext(), backEndTexture,
Cary Clark471b6fe2018-03-21 08:52:41 -04002212 kTopLeft_GrSurfaceOrigin, kN32_SkColorType, kOpaque_SkAlphaType,
2213 nullptr));
Cary Clarkf5404bb2018-01-05 12:10:09 -05002214 drawImage(image, "image");
2215 canvas->translate(image->width(), 0);
2216 drawImage(bitmapImage, "source");
2217 canvas->translate(-image->width(), image->height());
2218 drawImage(textureImage, "backEndTexture");
2219}
2220##
2221
Cary Clarkac47b882018-01-11 10:35:44 -05002222#SeeAlso isTextureBacked MakeNonTextureImage
Cary Clarka560c472017-11-27 10:44:06 -05002223
2224#Method ##
2225
2226# ------------------------------------------------------------------------------
2227
2228#Method sk_sp<SkImage> makeColorSpace(sk_sp<SkColorSpace> target,
2229 SkTransferFunctionBehavior premulBehavior) const
Cary Clark4855f782018-02-06 09:41:53 -05002230#In Constructor
2231#Line # creates Image matching Color_Space if possible ##
Cary Clarka560c472017-11-27 10:44:06 -05002232
Cary Clarkac47b882018-01-11 10:35:44 -05002233Creates Image in target Color_Space.
2234Returns nullptr if Image could not be created.
Cary Clarka560c472017-11-27 10:44:06 -05002235
Cary Clarkac47b882018-01-11 10:35:44 -05002236Returns original Image if it is in target Color_Space.
2237Otherwise, converts pixels from Image Color_Space to target Color_Space.
2238If Image colorSpace returns nullptr, Image Color_Space is assumed to be sRGB.
2239
2240SkTransferFunctionBehavior is to be deprecated.
2241
2242Set premulBehavior to SkTransferFunctionBehavior::kRespect to convert Image
2243pixels to a linear space, before converting to destination Color_Type
Cary Clarka560c472017-11-27 10:44:06 -05002244and Color_Space.
Cary Clarka560c472017-11-27 10:44:06 -05002245
Cary Clarkac47b882018-01-11 10:35:44 -05002246Set premulBehavior to SkTransferFunctionBehavior::kIgnore to treat Image
2247pixels as linear, when converting to destination Color_Type
2248and Color_Space, ignoring pixel encoding.
Cary Clarka560c472017-11-27 10:44:06 -05002249
Cary Clarkac47b882018-01-11 10:35:44 -05002250#Param target Color_Space describing color range of returned Image ##
2251#Param premulBehavior one of: SkTransferFunctionBehavior::kRespect,
2252 SkTransferFunctionBehavior::kIgnore
Cary Clarka560c472017-11-27 10:44:06 -05002253##
2254
Cary Clarkac47b882018-01-11 10:35:44 -05002255#Return created Image in target Color_Space ##
2256
2257#Example
2258#Image 5
2259#Set sRGB
2260 sk_sp<SkColorSpace> normalColorSpace = SkColorSpace::MakeRGB(
2261 SkColorSpace::kSRGB_RenderTargetGamma, SkColorSpace::kSRGB_Gamut);
2262 sk_sp<SkColorSpace> wackyColorSpace = normalColorSpace->makeColorSpin();
2263 for (auto colorSpace : { normalColorSpace, wackyColorSpace } ) {
2264 for (auto transfer : { SkTransferFunctionBehavior::kRespect,
2265 SkTransferFunctionBehavior::kIgnore } ) {
2266 sk_sp<SkImage> colorSpaced = image->makeColorSpace(colorSpace, transfer);
2267 canvas->drawImage(colorSpaced, 0, 0);
2268 canvas->translate(128, 0);
2269 }
2270 canvas->translate(-256, 128);
2271 }
2272##
2273
2274#SeeAlso MakeFromPixture MakeFromTexture
Cary Clarka560c472017-11-27 10:44:06 -05002275
2276#Method ##
2277
2278#Class SkImage ##
2279
2280#Topic Image ##