blob: 27aa62503e00a0c69dde0a9c6a4c808292861110 [file] [log] [blame]
Cary Clarka560c472017-11-27 10:44:06 -05001#Topic Image
Cary Clark137b8742018-05-30 09:21:49 -04002#Alias Image_Reference ##
Cary Clarka560c472017-11-27 10:44:06 -05003
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 Clark137b8742018-05-30 09:21:49 -040022#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 Clarkae957c42018-06-07 17:07:17 -0400402 origin, kRGBA_8888_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
Cary Clarkcdc371a2018-09-18 07:31:37 -0400655#SeeAlso MakeFromYUVTexturesCopyWithExternalBackend MakeFromNV12TexturesCopy
656
657#Method ##
658
659#Method static sk_sp<SkImage> MakeFromYUVTexturesCopyWithExternalBackend(
660 GrContext* context, SkYUVColorSpace yuvColorSpace,
661 const GrBackendTexture yuvTextures[3], GrSurfaceOrigin surfaceOrigin,
662 const GrBackendTexture backendTexture, sk_sp<SkColorSpace> colorSpace = nullptr);
663#In Constructor
664#Line # creates Image from planar YUV_ColorSpace, stored in texture ##
665
666Creates Image from copy of yuvTextures, an array of textures on GPU.
667yuvTextures contain pixels for YUV planes of Image. Returned Image has the dimensions
668yuvTextures[0] and stores pixels in backendTexture. yuvColorSpace describes how YUV colors
669convert to RGB colors.
670
671#Param context GPU_Context ##
672#Param yuvColorSpace one of: kJPEG_SkYUVColorSpace, kRec601_SkYUVColorSpace,
673 kRec709_SkYUVColorSpace
674##
675#Param yuvTextures array of YUV textures on GPU ##
676#Param surfaceOrigin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin ##
677#Param backendTexture the resource that stores the final pixels ##
678#Param colorSpace range of colors; may be nullptr ##
679
680#Return created SkImage, or nullptr ##
681
682# seems too complicated to create an example for this
683#ToDo
684should this be moved to chrome only?
685##
686
687#NoExample
688##
689
690#SeeAlso MakeFromYUVTexturesCopy MakeFromNV12TexturesCopy
Cary Clark61ca7c52018-01-02 11:34:14 -0500691
692#Method ##
693
694# ------------------------------------------------------------------------------
695
Cary Clarka560c472017-11-27 10:44:06 -0500696#Method static sk_sp<SkImage> MakeFromNV12TexturesCopy(GrContext* context,
697 SkYUVColorSpace yuvColorSpace,
Brian Salomon6a426c12018-03-15 12:16:02 -0400698 const GrBackendTexture nv12Textures[2],
Cary Clarka560c472017-11-27 10:44:06 -0500699 GrSurfaceOrigin surfaceOrigin,
700 sk_sp<SkColorSpace> colorSpace = nullptr)
Cary Clark4855f782018-02-06 09:41:53 -0500701#In Constructor
Brian Salomon6a426c12018-03-15 12:16:02 -0400702#Line # creates Image from YUV_ColorSpace data in three planes ##
Cary Clarka560c472017-11-27 10:44:06 -0500703
Cary Clark681287e2018-03-16 11:34:15 -0400704Creates Image from copy of nv12Textures, an array of textures on GPU.
Brian Salomon6a426c12018-03-15 12:16:02 -0400705nv12Textures[0] contains pixels for YUV_Component_Y plane.
706nv12Textures[1] contains pixels for YUV_Component_U plane,
Cary Clark61ca7c52018-01-02 11:34:14 -0500707followed by pixels for YUV_Component_V plane.
Cary Clark681287e2018-03-16 11:34:15 -0400708Returned Image has the dimensions nv12Textures[2].
709yuvColorSpace describes how YUV colors convert to RGB colors.
Cary Clarka560c472017-11-27 10:44:06 -0500710
Cary Clark61ca7c52018-01-02 11:34:14 -0500711#Param context GPU_Context ##
712#Param yuvColorSpace one of: kJPEG_SkYUVColorSpace, kRec601_SkYUVColorSpace,
713 kRec709_SkYUVColorSpace
714##
Brian Salomon6a426c12018-03-15 12:16:02 -0400715#Param nv12Textures array of YUV textures on GPU ##
Cary Clark61ca7c52018-01-02 11:34:14 -0500716#Param surfaceOrigin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin ##
717#Param colorSpace range of colors; may be nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -0500718
Cary Clark61ca7c52018-01-02 11:34:14 -0500719#Return created Image, or nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -0500720
Cary Clark61ca7c52018-01-02 11:34:14 -0500721# seems too complicated to create an example for this
722#ToDo
723should this be moved to chrome only?
Cary Clarka560c472017-11-27 10:44:06 -0500724##
725
Cary Clark61ca7c52018-01-02 11:34:14 -0500726#NoExample
727##
728
Cary Clarkcdc371a2018-09-18 07:31:37 -0400729#SeeAlso MakeFromNV12TexturesCopyWithExternalBackend MakeFromYUVTexturesCopy
730
731#Method ##
732
733#Method static sk_sp<SkImage> MakeFromNV12TexturesCopyWithExternalBackend(
734 GrContext* context,
735 SkYUVColorSpace yuvColorSpace,
736 const GrBackendTexture nv12Textures[2],
737 GrSurfaceOrigin surfaceOrigin,
738 const GrBackendTexture backendTexture,
739 sk_sp<SkColorSpace> colorSpace = nullptr);
740#In Constructor
741#Line # creates Image from planar YUV_ColorSpace, stored in texture ##
742
743Creates Image from copy of nv12Textures, an array of textures on GPU.
744nv12Textures[0] contains pixels for YUV_Component_Y plane.
745nv12Textures[1] contains pixels for YUV_Component_U plane,
746followed by pixels for YUV_Component_V plane.
747Returned Image has the dimensions nv12Textures[2] and stores pixels in backendTexture.
748yuvColorSpace describes how YUV colors convert to RGB colors.
749
750#Param context GPU_Context ##
751#Param yuvColorSpace one of: kJPEG_SkYUVColorSpace, kRec601_SkYUVColorSpace,
752 kRec709_SkYUVColorSpace
753##
754#Param nv12Textures array of YUV textures on GPU ##
755#Param surfaceOrigin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin ##
756#Param backendTexture the resource that stores the final pixels ##
757#Param colorSpace range of colors; may be nullptr ##
758
759#Return created Image, or nullptr ##
760
761# seems too complicated to create an example for this
762#ToDo
763should this be moved to chrome only?
764##
765
766#NoExample
767##
768
769#SeeAlso MakeFromNV12TexturesCopy MakeFromYUVTexturesCopy
Cary Clarka560c472017-11-27 10:44:06 -0500770
771#Method ##
772
773# ------------------------------------------------------------------------------
774
Cary Clark4855f782018-02-06 09:41:53 -0500775# currently uncalled by any test or client ##
Cary Clark61ca7c52018-01-02 11:34:14 -0500776#Bug 7424
Cary Clark61ca7c52018-01-02 11:34:14 -0500777
Cary Clark56356312018-02-08 14:45:18 -0500778#EnumClass BitDepth
Cary Clark682c58d2018-05-16 07:07:07 -0400779#Line # options for MakeFromPicture ##
Cary Clarka560c472017-11-27 10:44:06 -0500780#Code
Cary Clark61ca7c52018-01-02 11:34:14 -0500781 enum class BitDepth {
Cary Clarka560c472017-11-27 10:44:06 -0500782 kU8,
783 kF16,
784 };
785##
786
787#Const kU8 0
Cary Clark682c58d2018-05-16 07:07:07 -0400788#Line # uses 8-bit unsigned int per Color component ##
Cary Clarkffb3d682018-05-17 12:17:28 -0400789Use 8 bits per ARGB component using unsigned integer format.
Cary Clarka560c472017-11-27 10:44:06 -0500790##
791#Const kF16 1
Cary Clark682c58d2018-05-16 07:07:07 -0400792#Line # uses 16-bit float per Color component ##
Cary Clarkffb3d682018-05-17 12:17:28 -0400793Use 16 bits per ARGB component using half-precision floating point format.
Cary Clarka560c472017-11-27 10:44:06 -0500794##
795
Cary Clark61ca7c52018-01-02 11:34:14 -0500796#NoExample
Cary Clarka560c472017-11-27 10:44:06 -0500797##
798
Cary Clark61ca7c52018-01-02 11:34:14 -0500799#SeeAlso MakeFromPicture
Cary Clarka560c472017-11-27 10:44:06 -0500800
Cary Clark56356312018-02-08 14:45:18 -0500801#EnumClass ##
Cary Clarka560c472017-11-27 10:44:06 -0500802
803# ------------------------------------------------------------------------------
804
805#Method static sk_sp<SkImage> MakeFromPicture(sk_sp<SkPicture> picture, const SkISize& dimensions,
806 const SkMatrix* matrix, const SkPaint* paint,
807 BitDepth bitDepth,
808 sk_sp<SkColorSpace> colorSpace)
Cary Clark4855f782018-02-06 09:41:53 -0500809#In Constructor
810#Line # creates Image from Picture ##
Cary Clarka560c472017-11-27 10:44:06 -0500811
Cary Clark61ca7c52018-01-02 11:34:14 -0500812Creates Image from picture. Returned Image width and height are set by dimensions.
813Image draws picture with matrix and paint, set to bitDepth and colorSpace.
Cary Clarka560c472017-11-27 10:44:06 -0500814
Cary Clark61ca7c52018-01-02 11:34:14 -0500815If matrix is nullptr, draws with identity Matrix. If paint is nullptr, draws
Cary Clark682c58d2018-05-16 07:07:07 -0400816with default Paint. colorSpace may be nullptr.
Cary Clarka560c472017-11-27 10:44:06 -0500817
Cary Clark61ca7c52018-01-02 11:34:14 -0500818#Param picture stream of drawing commands ##
819#Param dimensions width and height ##
820#Param matrix Matrix to rotate, scale, translate, and so on; may be nullptr ##
821#Param paint Paint to apply transparency, filtering, and so on; may be nullptr ##
Cary Clark682c58d2018-05-16 07:07:07 -0400822#Param bitDepth 8-bit integer or 16-bit float: per component ##
Cary Clark61ca7c52018-01-02 11:34:14 -0500823#Param colorSpace range of colors; may be nullptr ##
824
825#Return created Image, or nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -0500826
827#Example
Cary Clark61ca7c52018-01-02 11:34:14 -0500828 SkPaint paint;
829 SkPictureRecorder recorder;
830 SkCanvas* recordingCanvas = recorder.beginRecording(50, 50);
831 for (auto color : { SK_ColorRED, SK_ColorBLUE, 0xff007f00 } ) {
832 paint.setColor(color);
833 recordingCanvas->drawRect({10, 10, 30, 40}, paint);
834 recordingCanvas->translate(10, 10);
835 recordingCanvas->scale(1.2f, 1.4f);
836 }
837 sk_sp<SkPicture> playback = recorder.finishRecordingAsPicture();
838 int x = 0, y = 0;
839 for (auto alpha : { 70, 140, 210 } ) {
840 paint.setAlpha(alpha);
841 auto srgbColorSpace = SkColorSpace::MakeSRGB();
842 sk_sp<SkImage> image = SkImage::MakeFromPicture(playback, {50, 50}, nullptr, &paint,
843 SkImage::BitDepth::kU8, srgbColorSpace);
844 canvas->drawImage(image, x, y);
845 x += 70; y += 70;
846 }
Cary Clarka560c472017-11-27 10:44:06 -0500847##
848
Cary Clark61ca7c52018-01-02 11:34:14 -0500849#SeeAlso SkCanvas::drawPicture
Cary Clarka560c472017-11-27 10:44:06 -0500850
851#Method ##
852
853# ------------------------------------------------------------------------------
854
Cary Clark9548ea92018-09-13 15:26:33 -0400855#Method static sk_sp<SkImage> MakeFromAHardwareBuffer(
856 AHardwareBuffer* hardwareBuffer,
857 SkAlphaType alphaType = kPremul_SkAlphaType,
858 sk_sp<SkColorSpace> colorSpace = nullptr,
859 GrSurfaceOrigin surfaceOrigin = kTopLeft_GrSurfaceOrigin)
Cary Clark4855f782018-02-06 09:41:53 -0500860#In Constructor
861#Line # creates Image from Android hardware buffer ##
Cary Clarka560c472017-11-27 10:44:06 -0500862
Cary Clark4855f782018-02-06 09:41:53 -0500863#Bug 7447
Cary Clarka560c472017-11-27 10:44:06 -0500864
Cary Clark61ca7c52018-01-02 11:34:14 -0500865Creates Image from Android hardware buffer.
866Returned Image takes a reference on the buffer.
Cary Clarka560c472017-11-27 10:44:06 -0500867
Cary Clark61ca7c52018-01-02 11:34:14 -0500868Only available on Android, when __ANDROID_API__ is defined to be 26 or greater.
Cary Clarka560c472017-11-27 10:44:06 -0500869
Cary Clark61ca7c52018-01-02 11:34:14 -0500870#Param hardwareBuffer AHardwareBuffer Android hardware buffer ##
Cary Clark681287e2018-03-16 11:34:15 -0400871#Param alphaType one of: #list_of_alpha_types#
Cary Clark61ca7c52018-01-02 11:34:14 -0500872##
873#Param colorSpace range of colors; may be nullptr ##
Cary Clark9548ea92018-09-13 15:26:33 -0400874#Param surfaceOrigin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin ##
Cary Clarka560c472017-11-27 10:44:06 -0500875
Cary Clark61ca7c52018-01-02 11:34:14 -0500876#Return created Image, or nullptr ##
877
878#NoExample
Cary Clarka560c472017-11-27 10:44:06 -0500879##
880
Cary Clark61ca7c52018-01-02 11:34:14 -0500881#SeeAlso MakeFromRaster
Cary Clarka560c472017-11-27 10:44:06 -0500882
883#Method ##
884
885# ------------------------------------------------------------------------------
Cary Clark4855f782018-02-06 09:41:53 -0500886#Subtopic Property
887#Populate
888#Line # values and attributes ##
889##
Cary Clarka560c472017-11-27 10:44:06 -0500890
891#Method int width() const
Cary Clark4855f782018-02-06 09:41:53 -0500892#In Property
893#Line # returns pixel column count ##
Cary Clark61ca7c52018-01-02 11:34:14 -0500894Returns pixel count in each row.
895
896#Return pixel width in Image ##
Cary Clarka560c472017-11-27 10:44:06 -0500897
898#Example
Cary Clark61ca7c52018-01-02 11:34:14 -0500899#Image 4
Cary Clarkac47b882018-01-11 10:35:44 -0500900#Height 96
Cary Clark61ca7c52018-01-02 11:34:14 -0500901 canvas->translate(10, 10);
902 canvas->drawImage(image, 0, 0);
903 canvas->translate(0, image->height());
904 SkPaint paint;
905 paint.setTextAlign(SkPaint::kCenter_Align);
906 canvas->drawLine(0, 10, image->width(), 10, paint);
907 canvas->drawString("width", image->width() / 2, 25, paint);
Cary Clarka560c472017-11-27 10:44:06 -0500908##
909
Cary Clark61ca7c52018-01-02 11:34:14 -0500910#SeeAlso dimensions() height()
Cary Clarka560c472017-11-27 10:44:06 -0500911
912#Method ##
913
914# ------------------------------------------------------------------------------
915
916#Method int height() const
Cary Clark4855f782018-02-06 09:41:53 -0500917#In Property
918#Line # returns pixel row count ##
Cary Clark2f466242017-12-11 16:03:17 -0500919Returns pixel row count.
920
Cary Clark61ca7c52018-01-02 11:34:14 -0500921#Return pixel height in Image ##
Cary Clarka560c472017-11-27 10:44:06 -0500922
923#Example
Cary Clark61ca7c52018-01-02 11:34:14 -0500924#Image 4
Cary Clarkac47b882018-01-11 10:35:44 -0500925#Height 96
Cary Clark61ca7c52018-01-02 11:34:14 -0500926 canvas->translate(10, 10);
927 canvas->drawImage(image, 0, 0);
928 canvas->translate(image->width(), 0);
929 SkPaint paint;
930 paint.setTextAlign(SkPaint::kCenter_Align);
931 paint.setVerticalText(true);
932 canvas->drawLine(10, 0, 10, image->height(), paint);
Cary Clarkac47b882018-01-11 10:35:44 -0500933 canvas->drawString("height", 25, image->height() / 2, paint);
934##
Cary Clarka560c472017-11-27 10:44:06 -0500935
Cary Clark61ca7c52018-01-02 11:34:14 -0500936#SeeAlso dimensions() width()
Cary Clarka560c472017-11-27 10:44:06 -0500937
938#Method ##
939
940# ------------------------------------------------------------------------------
941
942#Method SkISize dimensions() const
Cary Clark4855f782018-02-06 09:41:53 -0500943#In Property
944#Line # returns width() and height() ##
Cary Clark681287e2018-03-16 11:34:15 -0400945
Cary Clark2f466242017-12-11 16:03:17 -0500946Returns ISize { width(), height() }.
947
948#Return integral size of width() and height() ##
Cary Clarka560c472017-11-27 10:44:06 -0500949
950#Example
Cary Clark61ca7c52018-01-02 11:34:14 -0500951#Image 4
952 SkISize dimensions = image->dimensions();
953 SkIRect bounds = image->bounds();
954 SkIRect dimensionsAsBounds = SkIRect::MakeSize(dimensions);
955 SkDebugf("dimensionsAsBounds %c= bounds\n", dimensionsAsBounds == bounds ? '=' : '!');
Cary Clark681287e2018-03-16 11:34:15 -0400956#StdOut
957dimensionsAsBounds == bounds
958##
Cary Clarka560c472017-11-27 10:44:06 -0500959##
960
Cary Clark61ca7c52018-01-02 11:34:14 -0500961#SeeAlso height() width() bounds()
Cary Clarka560c472017-11-27 10:44:06 -0500962
963#Method ##
964
965# ------------------------------------------------------------------------------
966
967#Method SkIRect bounds() const
Cary Clark4855f782018-02-06 09:41:53 -0500968#In Property
969#Line # returns width() and height() as Rectangle ##
Cary Clark2f466242017-12-11 16:03:17 -0500970Returns IRect { 0, 0, width(), height() }.
971
972#Return integral rectangle from origin to width() and height() ##
Cary Clarka560c472017-11-27 10:44:06 -0500973
974#Example
Cary Clark61ca7c52018-01-02 11:34:14 -0500975#Height 128
976#Image 4
Cary Clark61ca7c52018-01-02 11:34:14 -0500977 SkIRect bounds = image->bounds();
Cary Clarkac47b882018-01-11 10:35:44 -0500978 for (int x : { 0, bounds.width() } ) {
979 for (int y : { 0, bounds.height() } ) {
Cary Clark61ca7c52018-01-02 11:34:14 -0500980 canvas->drawImage(image, x, y);
981 }
982 }
Cary Clarka560c472017-11-27 10:44:06 -0500983##
984
Cary Clark682c58d2018-05-16 07:07:07 -0400985#SeeAlso dimensions()
Cary Clarka560c472017-11-27 10:44:06 -0500986
987#Method ##
988
989# ------------------------------------------------------------------------------
990
991#Method uint32_t uniqueID() const
Cary Clark4855f782018-02-06 09:41:53 -0500992#In Property
Cary Clark682c58d2018-05-16 07:07:07 -0400993#Line # returns identifier for Image ##
Cary Clark61ca7c52018-01-02 11:34:14 -0500994Returns value unique to image. Image contents cannot change after Image is
995created. Any operation to create a new Image will receive generate a new
996unique number.
997
998#Return unique identifier ##
Cary Clarka560c472017-11-27 10:44:06 -0500999
1000#Example
Cary Clark61ca7c52018-01-02 11:34:14 -05001001#Image 5
1002#Height 156
1003 sk_sp<SkImage> subset = image->makeSubset({10, 20, 90, 100});
1004 canvas->drawImage(image, 0, 0);
1005 canvas->drawImage(subset, 128, 0);
1006 SkPaint paint;
1007 SkString s;
1008 s.printf("original id: %d", image->uniqueID());
1009 canvas->drawString(s, 20, image->height() + 20, paint);
1010 s.printf("subset id: %d", subset->uniqueID());
1011 canvas->drawString(s, 148, subset->height() + 20, paint);
Cary Clarka560c472017-11-27 10:44:06 -05001012##
1013
Cary Clark61ca7c52018-01-02 11:34:14 -05001014#SeeAlso isLazyGenerated
Cary Clarka560c472017-11-27 10:44:06 -05001015
1016#Method ##
1017
1018# ------------------------------------------------------------------------------
1019
1020#Method SkAlphaType alphaType() const
Cary Clark4855f782018-02-06 09:41:53 -05001021#In Property
1022#Line # returns Alpha_Type ##
Cary Clark681287e2018-03-16 11:34:15 -04001023Returns Alpha_Type, one of: #list_of_alpha_types#.
Cary Clark61ca7c52018-01-02 11:34:14 -05001024
1025Alpha_Type returned was a parameter to an Image constructor,
1026or was parsed from encoded data.
1027
1028#Return Alpha_Type in Image ##
Cary Clarka560c472017-11-27 10:44:06 -05001029
1030#Example
Cary Clark61ca7c52018-01-02 11:34:14 -05001031#Image 4
Cary Clarkac47b882018-01-11 10:35:44 -05001032#Height 96
Cary Clark61ca7c52018-01-02 11:34:14 -05001033 const char* alphaTypeStr[] = { "Unknown", "Opaque", "Premul", "Unpremul" };
1034 SkAlphaType alphaType = image->alphaType();
Cary Clarkac47b882018-01-11 10:35:44 -05001035 canvas->drawImage(image, 16, 0);
Cary Clarkffb3d682018-05-17 12:17:28 -04001036 canvas->drawString(alphaTypeStr[(int) alphaType], 20, image->height() + 20, SkPaint());
Cary Clarka560c472017-11-27 10:44:06 -05001037##
1038
Cary Clark61ca7c52018-01-02 11:34:14 -05001039#SeeAlso SkImageInfo::alphaType
Cary Clarka560c472017-11-27 10:44:06 -05001040
1041#Method ##
1042
1043# ------------------------------------------------------------------------------
1044
Greg Daniel56008aa2018-03-14 15:33:42 -04001045#Method SkColorType colorType() const
1046#In Property
1047#Line # returns Color_Type ##
1048
1049Returns Color_Type if known; otherwise, returns kUnknown_SkColorType.
1050
1051#Return Color_Type of Image ##
1052
1053#Example
Cary Clarkffb3d682018-05-17 12:17:28 -04001054#Image 4
1055#Height 96
1056 const char* colors[] = { "Unknown", "Alpha_8", "RGB_565", "ARGB_4444", "RGBA_8888", "RGB_888x",
1057 "BGRA_8888", "RGBA_1010102", "RGB_101010x", "Gray_8", "RGBA_F16" };
1058 SkColorType colorType = image->colorType();
1059 canvas->drawImage(image, 16, 0);
1060 canvas->drawString(colors[(int) colorType], 20, image->height() + 20, SkPaint());
Greg Daniel56008aa2018-03-14 15:33:42 -04001061##
1062
1063#SeeAlso SkImageInfo::colorType
1064
1065#Method ##
1066
1067# ------------------------------------------------------------------------------
1068
Cary Clarka560c472017-11-27 10:44:06 -05001069#Method SkColorSpace* colorSpace() const
Cary Clark4855f782018-02-06 09:41:53 -05001070#In Property
1071#Line # returns Color_Space ##
Cary Clark2f466242017-12-11 16:03:17 -05001072Returns Color_Space, the range of colors, associated with Image. The
1073reference count of Color_Space is unchanged. The returned Color_Space is
1074immutable.
Cary Clarka560c472017-11-27 10:44:06 -05001075
Cary Clark61dfc3a2018-01-03 08:37:53 -05001076Color_Space returned was passed to an Image constructor,
1077or was parsed from encoded data. Color_Space returned may be ignored when Image
1078is drawn, depending on the capabilities of the Surface receiving the drawing.
Cary Clark2f466242017-12-11 16:03:17 -05001079
1080#Return Color_Space in Image, or nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -05001081
1082#Example
Cary Clark61dfc3a2018-01-03 08:37:53 -05001083#Image 3
1084#Set sRGB
1085 SkPixmap pixmap;
1086 source.peekPixels(&pixmap);
1087 canvas->scale(.25f, .25f);
1088 int y = 0;
1089 for (auto gamma : { SkColorSpace::kLinear_RenderTargetGamma,
1090 SkColorSpace::kSRGB_RenderTargetGamma } ) {
1091 int x = 0;
1092 sk_sp<SkColorSpace> colorSpace = SkColorSpace::MakeRGB(gamma, SkColorSpace::kSRGB_Gamut);
1093 for (int index = 0; index < 2; ++index) {
1094 pixmap.setColorSpace(colorSpace);
1095 sk_sp<SkImage> image = SkImage::MakeRasterCopy(pixmap);
1096 canvas->drawImage(image, x, y);
1097 colorSpace = image->colorSpace()->makeColorSpin();
1098 x += 512;
1099 }
1100 y += 512;
1101 }
Cary Clarka560c472017-11-27 10:44:06 -05001102##
1103
Cary Clark61dfc3a2018-01-03 08:37:53 -05001104#SeeAlso refColorSpace makeColorSpace
Cary Clarka560c472017-11-27 10:44:06 -05001105
1106#Method ##
1107
1108# ------------------------------------------------------------------------------
1109
1110#Method sk_sp<SkColorSpace> refColorSpace() const
Cary Clark4855f782018-02-06 09:41:53 -05001111#In Property
1112#Line # returns Image_Info Color_Space ##
Cary Clark61dfc3a2018-01-03 08:37:53 -05001113Returns a smart pointer to Color_Space, the range of colors, associated with
1114Image. The smart pointer tracks the number of objects sharing this
1115SkColorSpace reference so the memory is released when the owners destruct.
1116
1117The returned SkColorSpace is immutable.
1118
1119Color_Space returned was passed to an Image constructor,
1120or was parsed from encoded data. Color_Space returned may be ignored when Image
1121is drawn, depending on the capabilities of the Surface receiving the drawing.
1122
1123#Return Color_Space in Image, or nullptr, wrapped in a smart pointer ##
Cary Clarka560c472017-11-27 10:44:06 -05001124
1125#Example
Cary Clark61dfc3a2018-01-03 08:37:53 -05001126#Image 3
1127#Set sRGB
1128 SkPixmap pixmap;
1129 source.peekPixels(&pixmap);
1130 canvas->scale(.25f, .25f);
1131 int y = 0;
1132 for (auto gamma : { SkColorSpace::kLinear_RenderTargetGamma,
1133 SkColorSpace::kSRGB_RenderTargetGamma } ) {
1134 int x = 0;
1135 sk_sp<SkColorSpace> colorSpace = SkColorSpace::MakeRGB(gamma, SkColorSpace::kSRGB_Gamut);
1136 for (int index = 0; index < 2; ++index) {
1137 pixmap.setColorSpace(colorSpace);
1138 sk_sp<SkImage> image = SkImage::MakeRasterCopy(pixmap);
1139 canvas->drawImage(image, x, y);
1140 colorSpace = image->refColorSpace()->makeColorSpin();
1141 x += 512;
1142 }
1143 y += 512;
1144 }
Cary Clarka560c472017-11-27 10:44:06 -05001145##
1146
Cary Clark61dfc3a2018-01-03 08:37:53 -05001147#SeeAlso colorSpace makeColorSpace
Cary Clarka560c472017-11-27 10:44:06 -05001148
1149#Method ##
1150
1151# ------------------------------------------------------------------------------
1152
1153#Method bool isAlphaOnly() const
Cary Clark4855f782018-02-06 09:41:53 -05001154#In Property
1155#Line # returns if pixels represent a transparency mask ##
Cary Clark2f466242017-12-11 16:03:17 -05001156Returns true if Image pixels represent transparency only. If true, each pixel
1157is packed in 8 bits as defined by kAlpha_8_SkColorType.
Cary Clarka560c472017-11-27 10:44:06 -05001158
Cary Clark2f466242017-12-11 16:03:17 -05001159#Return true if pixels represent a transparency mask ##
Cary Clarka560c472017-11-27 10:44:06 -05001160
1161#Example
Cary Clark61dfc3a2018-01-03 08:37:53 -05001162 uint8_t pmColors = 0;
1163 sk_sp<SkImage> image = SkImage::MakeRasterCopy({SkImageInfo::MakeA8(1, 1), &pmColors, 1});
1164 SkDebugf("alphaOnly = %s\n", image->isAlphaOnly() ? "true" : "false");
1165#StdOut
1166alphaOnly = true
1167##
Cary Clarka560c472017-11-27 10:44:06 -05001168##
1169
Cary Clark61dfc3a2018-01-03 08:37:53 -05001170#SeeAlso alphaType isOpaque
Cary Clarka560c472017-11-27 10:44:06 -05001171
1172#Method ##
1173
1174# ------------------------------------------------------------------------------
1175
1176#Method bool isOpaque() const
Cary Clark4855f782018-02-06 09:41:53 -05001177#In Property
1178#Line # returns if Alpha_Type is kOpaque_SkAlphaType ##
Cary Clark61dfc3a2018-01-03 08:37:53 -05001179Returns true if pixels ignore their Alpha value and are treated as fully opaque.
Cary Clark2f466242017-12-11 16:03:17 -05001180
1181#Return true if Alpha_Type is kOpaque_SkAlphaType ##
Cary Clarka560c472017-11-27 10:44:06 -05001182
1183#Example
Cary Clark61dfc3a2018-01-03 08:37:53 -05001184 auto check_isopaque = [](const SkImageInfo& imageInfo) -> void {
1185 auto surface(SkSurface::MakeRaster(imageInfo));
1186 auto image(surface->makeImageSnapshot());
1187 SkDebugf("isOpaque = %s\n", image->isOpaque() ? "true" : "false");
1188 };
1189
1190 check_isopaque(SkImageInfo::MakeN32Premul(5, 5));
1191 check_isopaque(SkImageInfo::MakeN32(5, 5, kOpaque_SkAlphaType));
1192#StdOut
1193isOpaque = false
1194isOpaque = true
1195##
Cary Clarka560c472017-11-27 10:44:06 -05001196##
1197
Cary Clark61dfc3a2018-01-03 08:37:53 -05001198#SeeAlso alphaType isAlphaOnly
Cary Clarka560c472017-11-27 10:44:06 -05001199
1200#Method ##
1201
1202# ------------------------------------------------------------------------------
1203
1204#Method sk_sp<SkShader> makeShader(SkShader::TileMode tileMode1, SkShader::TileMode tileMode2,
1205 const SkMatrix* localMatrix = nullptr) const
Cary Clark4855f782018-02-06 09:41:53 -05001206#In Constructor
1207#Line # creates Shader, Paint element that can tile Image ##
Cary Clarka560c472017-11-27 10:44:06 -05001208
Cary Clark61dfc3a2018-01-03 08:37:53 -05001209Creates Shader from Image. Shader dimensions are taken from Image. Shader uses
1210SkShader::TileMode rules to fill drawn area outside Image. localMatrix permits
1211transforming Image before Canvas_Matrix is applied.
Cary Clarka560c472017-11-27 10:44:06 -05001212
Cary Clark5538c132018-06-14 12:28:14 -04001213#Param tileMode1 tiling on x-axis, one of: SkShader::kClamp_TileMode,
1214 SkShader::kRepeat_TileMode, SkShader::kMirror_TileMode
Cary Clark61dfc3a2018-01-03 08:37:53 -05001215##
Cary Clark5538c132018-06-14 12:28:14 -04001216#Param tileMode2 tiling on y-axis, one of: SkShader::kClamp_TileMode,
1217 SkShader::kRepeat_TileMode, SkShader::kMirror_TileMode
Cary Clark61dfc3a2018-01-03 08:37:53 -05001218##
1219#Param localMatrix Image transformation, or nullptr ##
1220
1221#Return Shader containing Image ##
Cary Clarka560c472017-11-27 10:44:06 -05001222
1223#Example
Cary Clark61dfc3a2018-01-03 08:37:53 -05001224#Image 4
1225SkMatrix matrix;
1226matrix.setRotate(45);
1227SkPaint paint;
1228paint.setShader(image->makeShader(SkShader::kRepeat_TileMode, SkShader::kMirror_TileMode,
1229 &matrix));
1230canvas->drawPaint(paint);
Cary Clarka560c472017-11-27 10:44:06 -05001231##
1232
Cary Clark61dfc3a2018-01-03 08:37:53 -05001233#SeeAlso scalePixels
Cary Clarka560c472017-11-27 10:44:06 -05001234
1235#Method ##
1236
1237# ------------------------------------------------------------------------------
1238
1239#Method sk_sp<SkShader> makeShader(const SkMatrix* localMatrix = nullptr) const
1240
Cary Clark61dfc3a2018-01-03 08:37:53 -05001241Creates Shader from Image. Shader dimensions are taken from Image. Shader uses
1242SkShader::kClamp_TileMode to fill drawn area outside Image. localMatrix permits
1243transforming Image before Canvas_Matrix is applied.
Cary Clarka560c472017-11-27 10:44:06 -05001244
Cary Clark61dfc3a2018-01-03 08:37:53 -05001245#Param localMatrix Image transformation, or nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -05001246
Cary Clark61dfc3a2018-01-03 08:37:53 -05001247#Return Shader containing Image ##
Cary Clarka560c472017-11-27 10:44:06 -05001248
1249#Example
Cary Clark61dfc3a2018-01-03 08:37:53 -05001250#Image 5
1251SkMatrix matrix;
1252matrix.setRotate(45);
1253matrix.postTranslate(125, 30);
1254SkPaint paint;
1255paint.setShader(image->makeShader(&matrix));
1256canvas->drawPaint(paint);
Cary Clarka560c472017-11-27 10:44:06 -05001257##
1258
Cary Clarkf5404bb2018-01-05 12:10:09 -05001259#SeeAlso scalePixels
Cary Clarka560c472017-11-27 10:44:06 -05001260
1261#Method ##
1262
1263# ------------------------------------------------------------------------------
Cary Clark78de7512018-02-07 07:27:09 -05001264#Subtopic Pixels
1265#Populate
1266#Line # read and write pixel values ##
1267##
Cary Clarka560c472017-11-27 10:44:06 -05001268
1269#Method bool peekPixels(SkPixmap* pixmap) const
Cary Clark78de7512018-02-07 07:27:09 -05001270#In Pixels
Cary Clark4855f782018-02-06 09:41:53 -05001271#Line # returns Pixmap if possible ##
Cary Clarkf5404bb2018-01-05 12:10:09 -05001272Copies Image pixel address, row bytes, and Image_Info to pixmap, if address
1273is available, and returns true. If pixel address is not available, return
1274false and leave pixmap unchanged.
Cary Clarka560c472017-11-27 10:44:06 -05001275
Cary Clarkf5404bb2018-01-05 12:10:09 -05001276#Param pixmap storage for pixel state if pixels are readable; otherwise, ignored ##
Cary Clarka560c472017-11-27 10:44:06 -05001277
Cary Clarkf5404bb2018-01-05 12:10:09 -05001278#Return true if Image has direct access to pixels ##
Cary Clarka560c472017-11-27 10:44:06 -05001279
1280#Example
Cary Clarkf5404bb2018-01-05 12:10:09 -05001281 SkBitmap bitmap;
1282 bitmap.allocPixels(SkImageInfo::MakeN32Premul(12, 11));
1283 SkCanvas offscreen(bitmap);
1284 offscreen.clear(SK_ColorWHITE);
1285 SkPaint paint;
1286 offscreen.drawString("%", 1, 10, paint);
1287 sk_sp<SkImage> image = SkImage::MakeFromBitmap(bitmap);
1288 SkPixmap pixmap;
1289 if (image->peekPixels(&pixmap)) {
1290 const SkPMColor* pixels = pixmap.addr32();
1291 SkPMColor pmWhite = pixels[0];
1292 for (int y = 0; y < image->height(); ++y) {
1293 for (int x = 0; x < image->width(); ++x) {
1294 SkDebugf("%c", *pixels++ == pmWhite ? '-' : 'x');
1295 }
1296 SkDebugf("\n");
1297 }
1298 }
1299#StdOut
1300------------
1301--xx----x---
1302-x--x--x----
1303-x--x--x----
1304-x--x-x-----
1305--xx-xx-xx--
1306-----x-x--x-
1307----x--x--x-
1308----x--x--x-
1309---x----xx--
1310------------
1311##
Cary Clarka560c472017-11-27 10:44:06 -05001312##
1313
Cary Clarkf5404bb2018-01-05 12:10:09 -05001314#SeeAlso readPixels
Cary Clarka560c472017-11-27 10:44:06 -05001315
1316#Method ##
1317
1318# ------------------------------------------------------------------------------
1319
1320#Method GrTexture* getTexture() const
Cary Clark682c58d2018-05-16 07:07:07 -04001321#Deprecated
Cary Clarka560c472017-11-27 10:44:06 -05001322#Method ##
1323
1324# ------------------------------------------------------------------------------
1325
1326#Method bool isTextureBacked() const
Cary Clark78de7512018-02-07 07:27:09 -05001327#In Property
Cary Clark4855f782018-02-06 09:41:53 -05001328#Line # returns if Image was created from GPU_Texture ##
Cary Clarkf5404bb2018-01-05 12:10:09 -05001329Returns true the contents of Image was created on or uploaded to GPU memory,
1330and is available as a GPU_Texture.
Cary Clarka560c472017-11-27 10:44:06 -05001331
Cary Clarkf5404bb2018-01-05 12:10:09 -05001332#Return true if Image is a GPU_Texture ##
Cary Clarka560c472017-11-27 10:44:06 -05001333
1334#Example
Cary Clarkf5404bb2018-01-05 12:10:09 -05001335#Image 5
1336#Platform gpu
1337auto drawImage = [=](sk_sp<SkImage> image, const char* label) -> void {
1338 if (nullptr == image) {
1339 return;
1340 }
1341 SkPaint paint;
1342 paint.setAntiAlias(true);
1343 paint.setTextAlign(SkPaint::kCenter_Align);
1344 canvas->drawImage(image, 0, 0);
1345 canvas->drawString(label, image->width() / 2, image->height() / 4, paint);
1346 canvas->drawString(image->isTextureBacked() ? "is GPU texture" : "not GPU texture",
1347 image->width() / 2, image->height() * 3 / 4, paint);
1348};
1349sk_sp<SkImage> bitmapImage(SkImage::MakeFromBitmap(source));
1350sk_sp<SkImage> textureImage(SkImage::MakeFromTexture(canvas->getGrContext(), backEndTexture,
Cary Clarkae957c42018-06-07 17:07:17 -04001351 kTopLeft_GrSurfaceOrigin, kRGBA_8888_SkColorType,
1352 kOpaque_SkAlphaType, nullptr));
Cary Clarkf5404bb2018-01-05 12:10:09 -05001353drawImage(image, "image");
1354canvas->translate(image->width(), 0);
1355drawImage(bitmapImage, "source");
1356canvas->translate(-image->width(), image->height());
1357drawImage(textureImage, "backEndTexture");
Cary Clarka560c472017-11-27 10:44:06 -05001358##
1359
Cary Clarkf5404bb2018-01-05 12:10:09 -05001360#SeeAlso MakeFromTexture isValid
Cary Clarka560c472017-11-27 10:44:06 -05001361
1362#Method ##
1363
1364# ------------------------------------------------------------------------------
1365
1366#Method bool isValid(GrContext* context) const
Cary Clark4855f782018-02-06 09:41:53 -05001367#In Property
1368#Line # returns if Image can draw to Raster_Surface or GPU_Context ##
Cary Clarkf5404bb2018-01-05 12:10:09 -05001369Returns true if Image can be drawn on either Raster_Surface or GPU_Surface.
1370If context is nullptr, tests if Image draws on Raster_Surface;
1371otherwise, tests if Image draws on GPU_Surface associated with context.
Cary Clarka560c472017-11-27 10:44:06 -05001372
Cary Clarkf5404bb2018-01-05 12:10:09 -05001373Image backed by GPU_Texture may become invalid if associated GrContext is
1374invalid. Lazy_Image may be invalid and may not draw to Raster_Surface or
1375GPU_Surface or both.
Cary Clarka560c472017-11-27 10:44:06 -05001376
Cary Clark61ca7c52018-01-02 11:34:14 -05001377#Param context GPU_Context ##
Cary Clarka560c472017-11-27 10:44:06 -05001378
Cary Clarkf5404bb2018-01-05 12:10:09 -05001379#Return true if Image can be drawn ##
Cary Clarka560c472017-11-27 10:44:06 -05001380
1381#Example
Cary Clarkf5404bb2018-01-05 12:10:09 -05001382#Image 5
1383#Platform gpu
1384auto drawImage = [=](sk_sp<SkImage> image, const char* label) -> void {
1385 if (nullptr == image) {
1386 return;
1387 }
1388 SkPaint paint;
1389 paint.setAntiAlias(true);
1390 paint.setTextAlign(SkPaint::kCenter_Align);
1391 canvas->drawImage(image, 0, 0);
1392 canvas->drawString(label, image->width() / 2, image->height() / 4, paint);
1393 if (canvas->getGrContext()) {
1394 canvas->drawString(image->isValid(canvas->getGrContext()) ? "is valid on GPU" :
1395 "not valid on GPU", image->width() / 2, image->height() * 5 / 8, paint);
1396 }
1397 canvas->drawString(image->isValid(nullptr) ? "is valid on CPU" :
1398 "not valid on CPU", image->width() / 2, image->height() * 7 / 8, paint);
1399};
1400sk_sp<SkImage> bitmapImage(SkImage::MakeFromBitmap(source));
1401sk_sp<SkImage> textureImage(SkImage::MakeFromTexture(canvas->getGrContext(), backEndTexture,
Cary Clarkae957c42018-06-07 17:07:17 -04001402 kTopLeft_GrSurfaceOrigin, kRGBA_8888_SkColorType,
1403 kOpaque_SkAlphaType, nullptr));
Cary Clarkf5404bb2018-01-05 12:10:09 -05001404drawImage(image, "image");
1405canvas->translate(image->width(), 0);
1406drawImage(bitmapImage, "source");
1407canvas->translate(-image->width(), image->height());
1408drawImage(textureImage, "backEndTexture");
Cary Clarka560c472017-11-27 10:44:06 -05001409##
1410
Cary Clarkf5404bb2018-01-05 12:10:09 -05001411#SeeAlso isTextureBacked isLazyGenerated
Cary Clarka560c472017-11-27 10:44:06 -05001412
1413#Method ##
1414
1415# ------------------------------------------------------------------------------
1416
Robert Phillipsc5509952018-04-04 15:54:55 -04001417#Method GrBackendTexture getBackendTexture(bool flushPendingGrContextIO,
1418 GrSurfaceOrigin* origin = nullptr) const
1419#In Property
1420#Line # returns GPU reference to Image as texture ##
1421
Cary Clark682c58d2018-05-16 07:07:07 -04001422Retrieves the back-end texture. If Image has no back-end texture, an invalid
Cary Clarkba75aee2018-04-05 08:18:41 -04001423object is returned. Call GrBackendTexture::isValid to determine if the result
1424is valid.
1425
1426If flushPendingGrContextIO is true, completes deferred I/O operations.
Robert Phillipsc5509952018-04-04 15:54:55 -04001427
1428If origin in not nullptr, copies location of content drawn into Image.
1429
1430#Param flushPendingGrContextIO flag to flush outstanding requests ##
1431#Param origin storage for one of: kTopLeft_GrSurfaceOrigin,
1432 kBottomLeft_GrSurfaceOrigin; or nullptr
1433##
1434
Cary Clarkba75aee2018-04-05 08:18:41 -04001435#Return back-end API texture handle; invalid on failure ##
Robert Phillipsc5509952018-04-04 15:54:55 -04001436
Cary Clarkba75aee2018-04-05 08:18:41 -04001437#Example
1438#Image 3
1439#Platform gpu
Brian Osman584b5012018-04-13 15:48:26 -04001440 GrContext* grContext = canvas->getGrContext();
1441 if (!grContext) {
1442 canvas->drawString("GPU only!", 20, 40, SkPaint());
1443 return;
1444 }
1445 sk_sp<SkImage> imageFromBackend = SkImage::MakeFromAdoptedTexture(grContext, backEndTexture,
1446 kBottomLeft_GrSurfaceOrigin, kRGBA_8888_SkColorType, kOpaque_SkAlphaType);
1447 GrBackendTexture textureFromImage = imageFromBackend->getBackendTexture(false);
1448 if (!textureFromImage.isValid()) {
1449 return;
1450 }
1451 sk_sp<SkImage> imageFromTexture = SkImage::MakeFromAdoptedTexture(grContext, textureFromImage,
1452 kTopLeft_GrSurfaceOrigin, kRGBA_8888_SkColorType, kOpaque_SkAlphaType);
1453 canvas->drawImage(imageFromTexture, 0, 0);
Cary Clarkba75aee2018-04-05 08:18:41 -04001454 canvas->drawImage(imageFromBackend, 128, 128);
Robert Phillipsc5509952018-04-04 15:54:55 -04001455##
1456
1457#SeeAlso MakeFromTexture isTextureBacked
1458
1459#Method ##
1460
1461# ------------------------------------------------------------------------------
1462
Cary Clarka560c472017-11-27 10:44:06 -05001463#Enum CachingHint
Cary Clark682c58d2018-05-16 07:07:07 -04001464#Line # options for readPixels and scalePixels ##
Cary Clarka560c472017-11-27 10:44:06 -05001465#Code
1466 enum CachingHint {
1467 kAllow_CachingHint,
1468 kDisallow_CachingHint,
1469 };
1470##
1471
Cary Clarkac47b882018-01-11 10:35:44 -05001472CachingHint selects whether Skia may internally cache Bitmaps generated by
1473decoding Image, or by copying Image from GPU to CPU. The default behavior
Cary Clark682c58d2018-05-16 07:07:07 -04001474allows caching Bitmaps.
Cary Clarkac47b882018-01-11 10:35:44 -05001475
1476Choose kDisallow_CachingHint if Image pixels are to be used only once, or
1477if Image pixels reside in a cache outside of Skia, or to reduce memory pressure.
1478
1479Choosing kAllow_CachingHint does not ensure that pixels will be cached.
1480Image pixels may not be cached if memory requirements are too large or
1481pixels are not accessible.
Cary Clarka560c472017-11-27 10:44:06 -05001482
1483#Const kAllow_CachingHint 0
Cary Clark682c58d2018-05-16 07:07:07 -04001484#Line # allows internally caching decoded and copied pixels ##
Cary Clarka560c472017-11-27 10:44:06 -05001485##
1486#Const kDisallow_CachingHint 1
Cary Clark682c58d2018-05-16 07:07:07 -04001487#Line # disallows internally caching decoded and copied pixels ##
Cary Clarka560c472017-11-27 10:44:06 -05001488##
1489
Cary Clarkac47b882018-01-11 10:35:44 -05001490#NoExample
Cary Clarka560c472017-11-27 10:44:06 -05001491##
1492
Cary Clarkac47b882018-01-11 10:35:44 -05001493#SeeAlso readPixels scalePixels
Cary Clarka560c472017-11-27 10:44:06 -05001494
1495#Enum ##
1496
1497# ------------------------------------------------------------------------------
1498
1499#Method bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes,
1500 int srcX, int srcY, CachingHint cachingHint = kAllow_CachingHint) const
Cary Clark78de7512018-02-07 07:27:09 -05001501#In Pixels
Cary Clark4855f782018-02-06 09:41:53 -05001502#Line # copies and converts pixels ##
Cary Clarka560c472017-11-27 10:44:06 -05001503
Cary Clarkac47b882018-01-11 10:35:44 -05001504Copies Rect of pixels from Image to dstPixels. Copy starts at offset (srcX, srcY),
Cary Clark682c58d2018-05-16 07:07:07 -04001505and does not exceed Image (width(), height()).
Cary Clarkac47b882018-01-11 10:35:44 -05001506
1507dstInfo specifies width, height, Color_Type, Alpha_Type, and Color_Space of
1508destination. dstRowBytes specifics the gap from one destination row to the next.
1509Returns true if pixels are copied. Returns false if:
1510#List
1511# dstInfo.addr() equals nullptr ##
1512# dstRowBytes is less than dstInfo.minRowBytes ##
1513# Pixel_Ref is nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -05001514##
1515
Cary Clarkac47b882018-01-11 10:35:44 -05001516Pixels are copied only if pixel conversion is possible. If Image Color_Type is
1517kGray_8_SkColorType, or kAlpha_8_SkColorType; dstInfo.colorType must match.
1518If Image Color_Type is kGray_8_SkColorType, dstInfo.colorSpace must match.
1519If Image Alpha_Type is kOpaque_SkAlphaType, dstInfo.alphaType must
1520match. If Image Color_Space is nullptr, dstInfo.colorSpace must match. Returns
1521false if pixel conversion is not possible.
Cary Clarka560c472017-11-27 10:44:06 -05001522
Cary Clarkac47b882018-01-11 10:35:44 -05001523srcX and srcY may be negative to copy only top or left of source. Returns
Cary Clark682c58d2018-05-16 07:07:07 -04001524false if width() or height() is zero or negative.
Cary Clark2be81cf2018-09-13 12:04:30 -04001525Returns false if #Formula # abs(srcX) >= Image width() ##, or if #Formula # abs(srcY) >= Image height() ##.
Cary Clarka560c472017-11-27 10:44:06 -05001526
Cary Clarkac47b882018-01-11 10:35:44 -05001527If cachingHint is kAllow_CachingHint, pixels may be retained locally.
1528If cachingHint is kDisallow_CachingHint, pixels are not added to the local cache.
1529
1530#Param dstInfo destination width, height, Color_Type, Alpha_Type, Color_Space ##
1531#Param dstPixels destination pixel storage ##
1532#Param dstRowBytes destination row length ##
1533#Param srcX column index whose absolute value is less than width() ##
1534#Param srcY row index whose absolute value is less than height() ##
1535#Param cachingHint one of: kAllow_CachingHint, kDisallow_CachingHint ##
1536
1537#Return true if pixels are copied to dstPixels ##
Cary Clarka560c472017-11-27 10:44:06 -05001538
1539#Example
Cary Clarkac47b882018-01-11 10:35:44 -05001540#Image 3
1541 canvas->scale(.5f, .5f);
1542 const int width = 32;
1543 const int height = 32;
1544 std::vector<int32_t> dstPixels;
1545 dstPixels.resize(height * width * 4);
1546 SkImageInfo info = SkImageInfo::MakeN32Premul(width, height);
1547 for (int y = 0; y < 512; y += height ) {
1548 for (int x = 0; x < 512; x += width ) {
1549 if (image->readPixels(info, &dstPixels.front(), width * 4, x, y)) {
1550 SkPixmap dstPixmap(info, &dstPixels.front(), width * 4);
1551 SkBitmap bitmap;
1552 bitmap.installPixels(dstPixmap);
1553 canvas->drawBitmap(bitmap, 0, 0);
1554 }
1555 canvas->translate(48, 0);
1556 }
1557 canvas->translate(-16 * 48, 48);
1558 }
Cary Clarka560c472017-11-27 10:44:06 -05001559##
1560
Cary Clarkac47b882018-01-11 10:35:44 -05001561#SeeAlso scalePixels SkBitmap::readPixels SkPixmap::readPixels SkCanvas::readPixels SkSurface::readPixels
Cary Clarka560c472017-11-27 10:44:06 -05001562
1563#Method ##
1564
1565# ------------------------------------------------------------------------------
1566
1567#Method bool readPixels(const SkPixmap& dst, int srcX, int srcY,
1568 CachingHint cachingHint = kAllow_CachingHint) const
1569
Cary Clarkac47b882018-01-11 10:35:44 -05001570Copies a Rect of pixels from Image to dst. Copy starts at (srcX, srcY), and
Cary Clark682c58d2018-05-16 07:07:07 -04001571does not exceed Image (width(), height()).
Cary Clarka560c472017-11-27 10:44:06 -05001572
Cary Clarkac47b882018-01-11 10:35:44 -05001573dst specifies width, height, Color_Type, Alpha_Type, Color_Space, pixel storage,
1574and row bytes of destination. dst.rowBytes specifics the gap from one destination
1575row to the next. Returns true if pixels are copied. Returns false if:
1576#List
1577# dst pixel storage equals nullptr ##
1578# dst.rowBytes is less than SkImageInfo::minRowBytes ##
1579# Pixel_Ref is nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -05001580##
1581
Cary Clarkac47b882018-01-11 10:35:44 -05001582Pixels are copied only if pixel conversion is possible. If Image Color_Type is
1583kGray_8_SkColorType, or kAlpha_8_SkColorType; dst.colorType must match.
1584If Image Color_Type is kGray_8_SkColorType, dst.colorSpace must match.
1585If Image Alpha_Type is kOpaque_SkAlphaType, dst.alphaType must
1586match. If Image Color_Space is nullptr, dst.colorSpace must match. Returns
1587false if pixel conversion is not possible.
Cary Clark682c58d2018-05-16 07:07:07 -04001588
Cary Clarkac47b882018-01-11 10:35:44 -05001589srcX and srcY may be negative to copy only top or left of source. Returns
Cary Clark682c58d2018-05-16 07:07:07 -04001590false if width() or height() is zero or negative.
Cary Clark2be81cf2018-09-13 12:04:30 -04001591Returns false if #Formula # abs(srcX) >= Image width() ##, or if #Formula # abs(srcY) >= Image height() ##.
Cary Clarkac47b882018-01-11 10:35:44 -05001592
1593If cachingHint is kAllow_CachingHint, pixels may be retained locally.
1594If cachingHint is kDisallow_CachingHint, pixels are not added to the local cache.
1595
1596#Param dst destination Pixmap: Image_Info, pixels, row bytes ##
1597#Param srcX column index whose absolute value is less than width() ##
1598#Param srcY row index whose absolute value is less than height() ##
1599#Param cachingHint one of: kAllow_CachingHint, kDisallow_CachingHint ##
1600
1601#Return true if pixels are copied to dst ##
1602
1603#Example
1604#Image 3
1605 std::vector<int32_t> srcPixels;
1606 int rowBytes = image->width() * 4;
1607 int quarterWidth = image->width() / 4;
1608 int quarterHeight = image->height() / 4;
1609 srcPixels.resize(image->height() * rowBytes);
1610 for (int y = 0; y < 4; ++y) {
1611 for (int x = 0; x < 4; ++x) {
1612 SkPixmap pixmap(SkImageInfo::MakeN32Premul(quarterWidth, quarterHeight),
1613 &srcPixels.front() + x * image->height() * quarterWidth +
1614 y * quarterWidth, rowBytes);
1615 image->readPixels(pixmap, x * quarterWidth, y * quarterHeight);
1616 }
1617 }
1618 canvas->scale(.5f, .5f);
1619 SkBitmap bitmap;
1620 bitmap.installPixels(SkImageInfo::MakeN32Premul(image->width(), image->height()),
1621 &srcPixels.front(), rowBytes);
1622 canvas->drawBitmap(bitmap, 0, 0);
1623##
1624
1625#SeeAlso scalePixels SkBitmap::readPixels SkPixmap::readPixels SkCanvas::readPixels SkSurface::readPixels
Cary Clarka560c472017-11-27 10:44:06 -05001626
1627#Method ##
1628
1629# ------------------------------------------------------------------------------
1630
1631#Method bool scalePixels(const SkPixmap& dst, SkFilterQuality filterQuality,
1632 CachingHint cachingHint = kAllow_CachingHint) const
Cary Clark78de7512018-02-07 07:27:09 -05001633#In Pixels
Cary Clark4855f782018-02-06 09:41:53 -05001634#Line # scales and converts one Image to another ##
Cary Clarka560c472017-11-27 10:44:06 -05001635
Cary Clarkac47b882018-01-11 10:35:44 -05001636Copies Image to dst, scaling pixels to fit dst.width() and dst.height(), and
1637converting pixels to match dst.colorType and dst.alphaType. Returns true if
1638pixels are copied. Returns false if dst.addr() is nullptr, or dst.rowBytes is
1639less than dst SkImageInfo::minRowBytes.
Cary Clarka560c472017-11-27 10:44:06 -05001640
Cary Clarkac47b882018-01-11 10:35:44 -05001641Pixels are copied only if pixel conversion is possible. If Image Color_Type is
1642kGray_8_SkColorType, or kAlpha_8_SkColorType; dst.colorType must match.
1643If Image Color_Type is kGray_8_SkColorType, dst.colorSpace must match.
1644If Image Alpha_Type is kOpaque_SkAlphaType, dst.alphaType must
1645match. If Image Color_Space is nullptr, dst.colorSpace must match. Returns
1646false if pixel conversion is not possible.
Cary Clarka560c472017-11-27 10:44:06 -05001647
Cary Clarkac47b882018-01-11 10:35:44 -05001648Scales the image, with filterQuality, to match dst.width() and dst.height().
1649filterQuality kNone_SkFilterQuality is fastest, typically implemented with
1650Filter_Quality_Nearest_Neighbor. kLow_SkFilterQuality is typically implemented with
1651Filter_Quality_Bilerp. kMedium_SkFilterQuality is typically implemented with
1652Filter_Quality_Bilerp, and Filter_Quality_MipMap when size is reduced.
1653kHigh_SkFilterQuality is slowest, typically implemented with Filter_Quality_BiCubic.
1654
1655If cachingHint is kAllow_CachingHint, pixels may be retained locally.
1656If cachingHint is kDisallow_CachingHint, pixels are not added to the local cache.
1657
1658#Param dst destination Pixmap: Image_Info, pixels, row bytes ##
1659#Param filterQuality one of: kNone_SkFilterQuality, kLow_SkFilterQuality,
1660 kMedium_SkFilterQuality, kHigh_SkFilterQuality
1661##
1662#Param cachingHint one of: kAllow_CachingHint, kDisallow_CachingHint ##
1663
1664#Return true if pixels are scaled to fit dst ##
Cary Clarka560c472017-11-27 10:44:06 -05001665
1666#Example
Cary Clarkac47b882018-01-11 10:35:44 -05001667#Image 3
1668#Height 128
1669 std::vector<int32_t> srcPixels;
1670 int quarterWidth = image->width() / 16;
1671 int rowBytes = quarterWidth * 4;
1672 int quarterHeight = image->height() / 16;
1673 srcPixels.resize(quarterHeight * rowBytes);
1674 SkPixmap pixmap(SkImageInfo::MakeN32Premul(quarterWidth, quarterHeight),
1675 &srcPixels.front(), rowBytes);
1676 canvas->scale(4, 4);
1677 SkFilterQuality qualities[] = { kNone_SkFilterQuality, kLow_SkFilterQuality,
1678 kMedium_SkFilterQuality, kHigh_SkFilterQuality };
1679 for (unsigned index = 0; index < SK_ARRAY_COUNT(qualities); ++index) {
1680 image->scalePixels(pixmap, qualities[index]);
1681 sk_sp<SkImage> filtered = SkImage::MakeFromRaster(pixmap, nullptr, nullptr);
1682 canvas->drawImage(filtered, 16 * index, 0);
1683 }
Cary Clarka560c472017-11-27 10:44:06 -05001684##
1685
Cary Clarkac47b882018-01-11 10:35:44 -05001686#SeeAlso SkCanvas::drawImage readPixels SkPixmap::scalePixels
Cary Clarka560c472017-11-27 10:44:06 -05001687
1688#Method ##
1689
1690# ------------------------------------------------------------------------------
1691
1692#Method sk_sp<SkData> encodeToData(SkEncodedImageFormat encodedImageFormat, int quality) const
Cary Clark78de7512018-02-07 07:27:09 -05001693#In Utility
Cary Clark4855f782018-02-06 09:41:53 -05001694#Line # returns encoded Image as SkData ##
Cary Clark682c58d2018-05-16 07:07:07 -04001695Encodes Image pixels, returning result as SkData.
Cary Clark2f466242017-12-11 16:03:17 -05001696
Cary Clarkac47b882018-01-11 10:35:44 -05001697Returns nullptr if encoding fails, or if encodedImageFormat is not supported.
Cary Clarka560c472017-11-27 10:44:06 -05001698
Cary Clarkac47b882018-01-11 10:35:44 -05001699Image encoding in a format requires both building with one or more of:
1700SK_HAS_JPEG_LIBRARY, SK_HAS_PNG_LIBRARY, SK_HAS_WEBP_LIBRARY; and platform support
1701for the encoded format.
1702
1703If SK_BUILD_FOR_MAC or SK_BUILD_FOR_IOS is defined, encodedImageFormat can
1704additionally be one of: SkEncodedImageFormat::kICO, SkEncodedImageFormat::kBMP,
1705SkEncodedImageFormat::kGIF.
1706
1707quality is a platform and format specific metric trading off size and encoding
1708error. When used, quality equaling 100 encodes with the least error. quality may
1709be ignored by the encoder.
1710
1711#Param encodedImageFormat one of: SkEncodedImageFormat::kJPEG, SkEncodedImageFormat::kPNG,
1712 SkEncodedImageFormat::kWEBP
1713 ##
1714#Param quality encoder specific metric with 100 equaling best ##
Cary Clarka560c472017-11-27 10:44:06 -05001715
Cary Clark2f466242017-12-11 16:03:17 -05001716#Return encoded Image, or nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -05001717
1718#Example
Cary Clarkac47b882018-01-11 10:35:44 -05001719#Image 3
1720 canvas->scale(4, 4);
1721 SkIRect subset = {0, 0, 16, 64};
1722 int x = 0;
1723 for (int quality : { 0, 10, 50, 100 } ) {
1724 sk_sp<SkData> data(image->encodeToData(SkEncodedImageFormat::kJPEG, quality));
1725 sk_sp<SkImage> filtered = SkImage::MakeFromEncoded(data, &subset);
1726 canvas->drawImage(filtered, x, 0);
1727 x += 16;
1728 }
Cary Clarka560c472017-11-27 10:44:06 -05001729##
1730
Cary Clarkac47b882018-01-11 10:35:44 -05001731#SeeAlso refEncodedData MakeFromEncoded
Cary Clarka560c472017-11-27 10:44:06 -05001732
1733#Method ##
1734
1735# ------------------------------------------------------------------------------
1736
Cary Clark61ca7c52018-01-02 11:34:14 -05001737#Method sk_sp<SkData> encodeToData() const
Cary Clarka560c472017-11-27 10:44:06 -05001738
Cary Clarkac47b882018-01-11 10:35:44 -05001739Encodes Image pixels, returning result as SkData. Returns existing encoded data
1740if present; otherwise, Image is encoded with SkEncodedImageFormat::kPNG. Skia
1741must be built with SK_HAS_PNG_LIBRARY to encode Image.
Cary Clarka560c472017-11-27 10:44:06 -05001742
Cary Clark682c58d2018-05-16 07:07:07 -04001743Returns nullptr if existing encoded data is missing or invalid, and
Cary Clarka560c472017-11-27 10:44:06 -05001744encoding fails.
1745
Cary Clarkac47b882018-01-11 10:35:44 -05001746#Return encoded Image, or nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -05001747
1748#Example
Cary Clarkac47b882018-01-11 10:35:44 -05001749#Image 3
1750 canvas->scale(4, 4);
1751 SkIRect subset = {136, 32, 200, 96};
1752 sk_sp<SkData> data(image->encodeToData());
1753 sk_sp<SkImage> eye = SkImage::MakeFromEncoded(data, &subset);
1754 canvas->drawImage(eye, 0, 0);
Cary Clarka560c472017-11-27 10:44:06 -05001755##
1756
Cary Clarkac47b882018-01-11 10:35:44 -05001757#SeeAlso refEncodedData MakeFromEncoded
Cary Clarka560c472017-11-27 10:44:06 -05001758
1759#Method ##
1760
1761# ------------------------------------------------------------------------------
1762
1763#Method sk_sp<SkData> refEncodedData() const
Cary Clark78de7512018-02-07 07:27:09 -05001764#In Utility
Cary Clark4855f782018-02-06 09:41:53 -05001765#Line # returns Image encoded in SkData if present ##
Cary Clarkac47b882018-01-11 10:35:44 -05001766Returns encoded Image pixels as SkData, if Image was created from supported
1767encoded stream format. Platform support for formats vary and may require building
1768with one or more of: SK_HAS_JPEG_LIBRARY, SK_HAS_PNG_LIBRARY, SK_HAS_WEBP_LIBRARY.
Cary Clarka560c472017-11-27 10:44:06 -05001769
Cary Clarkac47b882018-01-11 10:35:44 -05001770Returns nullptr if Image contents are not encoded.
Cary Clarka560c472017-11-27 10:44:06 -05001771
Cary Clarkac47b882018-01-11 10:35:44 -05001772#Return encoded Image, or nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -05001773
1774#Example
Cary Clarkac47b882018-01-11 10:35:44 -05001775#Image 3
1776#Platform gpu
1777 struct {
1778 const char* name;
1779 sk_sp<SkImage> image;
1780 } tests[] = { { "image", image }, { "bitmap", SkImage::MakeFromBitmap(source) },
1781 { "texture", SkImage::MakeFromTexture(canvas->getGrContext(), backEndTexture,
Cary Clarkae957c42018-06-07 17:07:17 -04001782 kTopLeft_GrSurfaceOrigin, kRGBA_8888_SkColorType,
1783 kOpaque_SkAlphaType, nullptr) } };
Cary Clarkac47b882018-01-11 10:35:44 -05001784 SkString string;
1785 SkPaint paint;
1786 for (const auto& test : tests ) {
1787 if (!test.image) {
1788 string.printf("no %s", test.name);
1789 } else {
1790 string.printf("%s" "encoded %s", test.image->refEncodedData() ? "" : "no ", test.name);
1791 }
1792 canvas->drawString(string, 10, 20, paint);
1793 canvas->translate(0, 20);
1794 }
Cary Clarka560c472017-11-27 10:44:06 -05001795##
1796
Cary Clarkac47b882018-01-11 10:35:44 -05001797#SeeAlso encodeToData MakeFromEncoded
Cary Clarka560c472017-11-27 10:44:06 -05001798
1799#Method ##
1800
1801# ------------------------------------------------------------------------------
Cary Clark4855f782018-02-06 09:41:53 -05001802#Subtopic Utility
1803#Populate
1804#Line # rarely called management functions ##
1805##
Cary Clarka560c472017-11-27 10:44:06 -05001806
Cary Clarka560c472017-11-27 10:44:06 -05001807#Method sk_sp<SkImage> makeSubset(const SkIRect& subset) const
Cary Clark4855f782018-02-06 09:41:53 -05001808#In Constructor
1809#Line # creates Image containing part of original ##
Cary Clarkac47b882018-01-11 10:35:44 -05001810Returns subset of Image. subset must be fully contained by Image dimensions().
1811The implementation may share pixels, or may copy them.
Cary Clarka560c472017-11-27 10:44:06 -05001812
Cary Clarkac47b882018-01-11 10:35:44 -05001813Returns nullptr if subset is empty, or subset is not contained by bounds, or
1814pixels in Image could not be read or copied.
Cary Clarka560c472017-11-27 10:44:06 -05001815
Cary Clarkac47b882018-01-11 10:35:44 -05001816#Param subset bounds of returned Image ##
1817
1818#Return partial or full Image, or nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -05001819
1820#Example
Cary Clarkac47b882018-01-11 10:35:44 -05001821#Image 3
1822 canvas->scale(.5f, .5f);
Cary Clarkc30382f2018-07-24 08:09:27 -04001823 const int width = 64;
1824 const int height = 64;
Cary Clarkac47b882018-01-11 10:35:44 -05001825 for (int y = 0; y < 512; y += height ) {
1826 for (int x = 0; x < 512; x += width ) {
1827 sk_sp<SkImage> subset(image->makeSubset({x, y, x + width, y + height}));
1828 canvas->drawImage(subset, x * 3 / 2, y * 3 / 2);
1829 }
1830 }
Cary Clarka560c472017-11-27 10:44:06 -05001831##
1832
Cary Clarkac47b882018-01-11 10:35:44 -05001833#SeeAlso MakeFromEncoded
Cary Clarka560c472017-11-27 10:44:06 -05001834
1835#Method ##
1836
1837# ------------------------------------------------------------------------------
1838
Greg Daniel5f4b09d2018-06-12 16:39:59 -04001839#Method sk_sp<SkImage> makeTextureImage(GrContext* context, SkColorSpace* dstColorSpace,
1840 GrMipMapped mipMapped = GrMipMapped::kNo) const
Cary Clark4855f782018-02-06 09:41:53 -05001841#In Constructor
1842#Line # creates Image matching Color_Space if possible ##
Cary Clarkac47b882018-01-11 10:35:44 -05001843Returns Image backed by GPU_Texture associated with context. Returned Image is
Cary Clark5538c132018-06-14 12:28:14 -04001844compatible with Surface created with dstColorSpace. The returned Image respects
1845mipMapped setting; if mipMapped equals GrMipMapped::kYes, the backing texture
1846allocates Mip_Map levels. Returns original Image if context
1847and dstColorSpace match and mipMapped is compatible with backing GPU_Texture.
Cary Clarkac47b882018-01-11 10:35:44 -05001848
1849Returns nullptr if context is nullptr, or if Image was created with another
1850GrContext.
Cary Clarka560c472017-11-27 10:44:06 -05001851
Cary Clark61ca7c52018-01-02 11:34:14 -05001852#Param context GPU_Context ##
Cary Clarkac47b882018-01-11 10:35:44 -05001853#Param dstColorSpace range of colors of matching Surface on GPU ##
Cary Clark5538c132018-06-14 12:28:14 -04001854#Param mipMapped whether created Image texture must allocate Mip_Map levels ##
Cary Clarka560c472017-11-27 10:44:06 -05001855
Cary Clarkac47b882018-01-11 10:35:44 -05001856#Return created Image, or nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -05001857
1858#Example
Cary Clarkac47b882018-01-11 10:35:44 -05001859#Platform gpu
1860#Image 5
1861 auto drawImage = [=](sk_sp<SkImage> image, GrContext* context, const char* label) -> void {
1862 if (nullptr == image || nullptr == context) {
1863 return;
1864 }
1865 SkPaint paint;
1866 paint.setAntiAlias(true);
1867 paint.setTextAlign(SkPaint::kCenter_Align);
1868 sk_sp<SkImage> texture(image->makeTextureImage(context, nullptr));
1869 canvas->drawImage(texture, 0, 0);
1870 canvas->drawString(label, texture->width() / 2, texture->height() / 4, paint);
1871 };
1872 sk_sp<SkImage> bitmapImage(SkImage::MakeFromBitmap(source));
1873 GrContext* context = canvas->getGrContext();
1874 sk_sp<SkImage> textureImage(SkImage::MakeFromTexture(context, backEndTexture,
Cary Clarkae957c42018-06-07 17:07:17 -04001875 kTopLeft_GrSurfaceOrigin, kRGBA_8888_SkColorType,
1876 kOpaque_SkAlphaType, nullptr));
Cary Clarkac47b882018-01-11 10:35:44 -05001877 drawImage(image, context, "image");
1878 canvas->translate(image->width(), 0);
1879 drawImage(bitmapImage, context, "source");
1880 canvas->translate(-image->width(), image->height());
1881 drawImage(textureImage, context, "backEndTexture");
Cary Clarka560c472017-11-27 10:44:06 -05001882##
1883
Cary Clarkac47b882018-01-11 10:35:44 -05001884#SeeAlso MakeFromTexture
Cary Clarka560c472017-11-27 10:44:06 -05001885
1886#Method ##
1887
1888# ------------------------------------------------------------------------------
1889
1890#Method sk_sp<SkImage> makeNonTextureImage() const
Cary Clark4855f782018-02-06 09:41:53 -05001891#In Constructor
1892#Line # creates Image without dependency on GPU_Texture ##
Cary Clarkac47b882018-01-11 10:35:44 -05001893Returns Raster_Image or Lazy_Image. Copies Image backed by GPU_Texture into
Cary Clark4855f782018-02-06 09:41:53 -05001894CPU memory if needed. Returns original Image if decoded in Raster_Bitmap,
Cary Clarkac47b882018-01-11 10:35:44 -05001895or if encoded in a stream.
Cary Clark61ca7c52018-01-02 11:34:14 -05001896
Cary Clarkac47b882018-01-11 10:35:44 -05001897Returns nullptr if backed by GPU_Texture and copy fails.
1898
1899#Return Raster_Image, Lazy_Image, or nullptr ##
Cary Clark61ca7c52018-01-02 11:34:14 -05001900
1901#Example
Cary Clarkac47b882018-01-11 10:35:44 -05001902#Image 5
1903#Platform gpu
1904 auto drawImage = [=](sk_sp<SkImage> image, const char* label) -> void {
1905 if (nullptr == image) {
1906 return;
1907 }
1908 SkPaint paint;
1909 paint.setAntiAlias(true);
1910 paint.setTextAlign(SkPaint::kCenter_Align);
1911 sk_sp<SkImage> nonTexture(image->makeNonTextureImage());
1912 canvas->drawImage(nonTexture, 0, 0);
1913 canvas->drawString(label, nonTexture->width() / 2, nonTexture->height() / 4, paint);
1914 };
1915 sk_sp<SkImage> bitmapImage(SkImage::MakeFromBitmap(source));
1916 sk_sp<SkImage> textureImage(SkImage::MakeFromTexture(canvas->getGrContext(), backEndTexture,
Cary Clarkae957c42018-06-07 17:07:17 -04001917 kTopLeft_GrSurfaceOrigin, kRGBA_8888_SkColorType,
1918 kOpaque_SkAlphaType, nullptr));
Cary Clarkac47b882018-01-11 10:35:44 -05001919 drawImage(image, "image");
1920 canvas->translate(image->width(), 0);
1921 drawImage(bitmapImage, "source");
1922 canvas->translate(-image->width(), image->height());
1923 drawImage(textureImage, "backEndTexture");
Cary Clark61ca7c52018-01-02 11:34:14 -05001924##
1925
Cary Clark56356312018-02-08 14:45:18 -05001926#SeeAlso makeTextureImage makeRasterImage MakeBackendTextureFromSkImage
Cary Clark61ca7c52018-01-02 11:34:14 -05001927
1928#Method ##
1929
1930# ------------------------------------------------------------------------------
1931
1932#Method sk_sp<SkImage> makeRasterImage() const
Cary Clark4855f782018-02-06 09:41:53 -05001933#In Constructor
1934#Line # creates Image compatible with Raster_Surface if possible ##
Cary Clarkac47b882018-01-11 10:35:44 -05001935Returns Raster_Image. Copies Image backed by GPU_Texture into CPU memory,
Cary Clark4855f782018-02-06 09:41:53 -05001936or decodes Image from Lazy_Image. Returns original Image if decoded in
Cary Clarkac47b882018-01-11 10:35:44 -05001937Raster_Bitmap.
Cary Clarka560c472017-11-27 10:44:06 -05001938
Cary Clarkac47b882018-01-11 10:35:44 -05001939Returns nullptr if copy, decode, or pixel read fails.
Cary Clarka560c472017-11-27 10:44:06 -05001940
Cary Clarkac47b882018-01-11 10:35:44 -05001941#Return Raster_Image, or nullptr ##
1942
Cary Clark4855f782018-02-06 09:41:53 -05001943#Bug 7479
Cary Clarka560c472017-11-27 10:44:06 -05001944#Example
Cary Clarkac47b882018-01-11 10:35:44 -05001945#Image 5
1946#Platform gpu
1947 auto drawImage = [=](sk_sp<SkImage> image, const char* label) -> void {
1948 if (nullptr == image) {
1949 return;
1950 }
1951 SkPaint paint;
1952 paint.setAntiAlias(true);
1953 paint.setTextAlign(SkPaint::kCenter_Align);
1954 sk_sp<SkImage> raster(image->makeRasterImage());
1955 canvas->drawImage(raster, 0, 0);
1956 canvas->drawString(label, raster->width() / 2, raster->height() / 4, paint);
1957 };
1958 sk_sp<SkImage> bitmapImage(SkImage::MakeFromBitmap(source));
1959 sk_sp<SkImage> textureImage(SkImage::MakeFromTexture(canvas->getGrContext(), backEndTexture,
Cary Clarkae957c42018-06-07 17:07:17 -04001960 kTopLeft_GrSurfaceOrigin, kRGBA_8888_SkColorType,
1961 kOpaque_SkAlphaType, nullptr));
Cary Clarkac47b882018-01-11 10:35:44 -05001962 drawImage(image, "image");
1963 canvas->translate(image->width(), 0);
1964 drawImage(bitmapImage, "source");
1965 canvas->translate(-image->width(), image->height());
1966 drawImage(textureImage, "backEndTexture");
Cary Clarka560c472017-11-27 10:44:06 -05001967##
1968
Cary Clarkac47b882018-01-11 10:35:44 -05001969#SeeAlso isTextureBacked isLazyGenerated MakeFromRaster
Cary Clarka560c472017-11-27 10:44:06 -05001970
1971#Method ##
1972
1973# ------------------------------------------------------------------------------
1974
1975#Method sk_sp<SkImage> makeWithFilter(const SkImageFilter* filter, const SkIRect& subset,
1976 const SkIRect& clipBounds, SkIRect* outSubset,
1977 SkIPoint* offset) const
Cary Clark4855f782018-02-06 09:41:53 -05001978#In Constructor
1979#Line # creates filtered, clipped Image ##
Cary Clarka560c472017-11-27 10:44:06 -05001980
Cary Clarkac47b882018-01-11 10:35:44 -05001981Creates filtered Image. filter processes original Image, potentially changing
1982color, position, and size. subset is the bounds of original Image processed
1983by filter. clipBounds is the expected bounds of the filtered Image. outSubset
1984is required storage for the actual bounds of the filtered Image. offset is
1985required storage for translation of returned Image.
Cary Clarka560c472017-11-27 10:44:06 -05001986
Cary Clarkac47b882018-01-11 10:35:44 -05001987Returns nullptr if Image could not be created. If nullptr is returned, outSubset
1988and offset are undefined.
1989
Cary Clark56356312018-02-08 14:45:18 -05001990Useful for animation of SkImageFilter that varies size from frame to frame.
1991Returned Image is created larger than required by filter so that GPU_Texture
1992can be reused with different sized effects. outSubset describes the valid bounds
1993of GPU_Texture returned. offset translates the returned Image to keep subsequent
1994animation frames aligned with respect to each other.
Cary Clarkac47b882018-01-11 10:35:44 -05001995
1996#Param filter how Image is sampled when transformed ##
Cary Clark56356312018-02-08 14:45:18 -05001997#Param subset bounds of Image processed by filter ##
1998#Param clipBounds expected bounds of filtered Image ##
1999#Param outSubset storage for returned Image bounds ##
2000#Param offset storage for returned Image translation ##
Cary Clarka560c472017-11-27 10:44:06 -05002001
Cary Clarkac47b882018-01-11 10:35:44 -05002002#Return filtered Image, or nullptr ##
Cary Clarka560c472017-11-27 10:44:06 -05002003
2004#Example
Cary Clarkac47b882018-01-11 10:35:44 -05002005#Description
2006In each frame of the animation, filtered Image is drawn in a different location.
2007By translating canvas by returned offset, Image appears stationary.
2008##
2009#Image 5
2010#Platform gpu
2011#Duration 5
2012 sk_sp<SkImageFilter> shadowFilter = SkDropShadowImageFilter::Make(
2013 -10.0f * frame, 5.0f * frame, 3.0f, 3.0f, SK_ColorBLUE,
2014 SkDropShadowImageFilter::kDrawShadowAndForeground_ShadowMode,
2015 nullptr);
2016 sk_sp<SkImageFilter> offsetFilter = SkOffsetImageFilter::Make(40, 40, shadowFilter, nullptr);
2017 SkIRect subset = image->bounds();
2018 SkIRect clipBounds = image->bounds();
2019 clipBounds.outset(60, 60);
2020 SkIRect outSubset;
2021 SkIPoint offset;
2022 sk_sp<SkImage> filtered(image->makeWithFilter(offsetFilter.get(), subset, clipBounds,
2023 &outSubset, &offset));
2024 SkPaint paint;
2025 paint.setAntiAlias(true);
2026 paint.setStyle(SkPaint::kStroke_Style);
2027 canvas->drawLine(0, 0, offset.fX, offset.fY, paint);
2028 canvas->translate(offset.fX, offset.fY);
2029 canvas->drawImage(filtered, 0, 0);
Cary Clark681287e2018-03-16 11:34:15 -04002030 canvas->drawRect(SkRect::Make(outSubset), paint);
Cary Clarka560c472017-11-27 10:44:06 -05002031##
2032
Cary Clark56356312018-02-08 14:45:18 -05002033#SeeAlso makeShader SkPaint::setImageFilter
Cary Clarka560c472017-11-27 10:44:06 -05002034
2035#Method ##
2036
2037# ------------------------------------------------------------------------------
2038
Cary Clarka560c472017-11-27 10:44:06 -05002039#Typedef std::function<void(GrBackendTexture)> BackendTextureReleaseProc
Cary Clark682c58d2018-05-16 07:07:07 -04002040#Line # parameter type for MakeBackendTextureFromSkImage ##
Cary Clarkffb3d682018-05-17 12:17:28 -04002041
2042#Code
2043typedef std::function<void(GrBackendTexture)> BackendTextureReleaseProc;
2044##
2045
Cary Clark0d225392018-06-07 09:59:07 -04002046Defines a callback function, taking one parameter of type GrBackendTexture with
2047no return value. Function is called when back-end texture is to be released.
Cary Clarka560c472017-11-27 10:44:06 -05002048##
2049
2050# ------------------------------------------------------------------------------
2051
2052#Method static bool MakeBackendTextureFromSkImage(GrContext* context,
2053 sk_sp<SkImage> image,
2054 GrBackendTexture* backendTexture,
2055 BackendTextureReleaseProc* backendTextureReleaseProc)
Cary Clark4855f782018-02-06 09:41:53 -05002056#In Constructor
2057#Line # creates GPU_Texture from Image ##
Cary Clarka560c472017-11-27 10:44:06 -05002058
Cary Clark56356312018-02-08 14:45:18 -05002059Creates a GrBackendTexture from the provided SkImage. Returns true and
2060stores result in backendTexture and backendTextureReleaseProc if
2061texture is created; otherwise, returns false and leaves
2062backendTexture and backendTextureReleaseProc unmodified.
Cary Clarka560c472017-11-27 10:44:06 -05002063
Cary Clark56356312018-02-08 14:45:18 -05002064Call backendTextureReleaseProc after deleting backendTexture.
2065backendTextureReleaseProc cleans up auxiliary data related to returned
2066backendTexture. The caller must delete returned backendTexture after use.
Cary Clarka560c472017-11-27 10:44:06 -05002067
Cary Clark56356312018-02-08 14:45:18 -05002068If Image is both texture backed and singly referenced, image is returned in
2069backendTexture without conversion or making a copy. Image is singly referenced
2070if its was transferred solely using std::move().
2071
2072If Image is not texture backed, returns texture with Image contents.
Cary Clarka560c472017-11-27 10:44:06 -05002073
Cary Clark61ca7c52018-01-02 11:34:14 -05002074#Param context GPU_Context ##
Cary Clark56356312018-02-08 14:45:18 -05002075#Param image Image used for texture ##
Cary Clark682c58d2018-05-16 07:07:07 -04002076#Param backendTexture storage for back-end texture ##
Cary Clark56356312018-02-08 14:45:18 -05002077#Param backendTextureReleaseProc storage for clean up function ##
Cary Clarka560c472017-11-27 10:44:06 -05002078
Cary Clark682c58d2018-05-16 07:07:07 -04002079#Return true if back-end texture was created ##
Cary Clarka560c472017-11-27 10:44:06 -05002080
2081#Example
Cary Clark56356312018-02-08 14:45:18 -05002082#Platform gpu
2083#Height 64
2084#Function
Brian Salomon67f85842018-02-09 08:50:22 -05002085static sk_sp<SkImage> create_gpu_image(GrContext* grContext) {
2086 const SkImageInfo info = SkImageInfo::MakeN32(20, 20, kOpaque_SkAlphaType);
2087 auto surface(SkSurface::MakeRenderTarget(grContext, SkBudgeted::kNo, info));
2088 SkCanvas* canvas = surface->getCanvas();
2089 canvas->clear(SK_ColorWHITE);
2090 SkPaint paint;
2091 paint.setColor(SK_ColorBLACK);
2092 canvas->drawRect(SkRect::MakeXYWH(5, 5, 10, 10), paint);
2093 return surface->makeImageSnapshot();
2094}
2095##
2096
Cary Clark682c58d2018-05-16 07:07:07 -04002097void draw(SkCanvas* canvas) {
Brian Salomon67f85842018-02-09 08:50:22 -05002098 GrContext* grContext = canvas->getGrContext();
2099 if (!grContext) {
2100 return;
2101 }
2102 sk_sp<SkImage> backEndImage = create_gpu_image(grContext);
2103 canvas->drawImage(backEndImage, 0, 0);
2104 GrBackendTexture texture;
2105 SkImage::BackendTextureReleaseProc proc;
2106 if (!SkImage::MakeBackendTextureFromSkImage(grContext, std::move(backEndImage),
2107 &texture, &proc)) {
2108 return;
2109 }
2110 sk_sp<SkImage> i2 = SkImage::MakeFromTexture(grContext, texture, kTopLeft_GrSurfaceOrigin,
2111 kN32_SkColorType, kOpaque_SkAlphaType, nullptr);
2112 canvas->drawImage(i2, 30, 30);
Cary Clark56356312018-02-08 14:45:18 -05002113}
Cary Clarka560c472017-11-27 10:44:06 -05002114##
2115
Cary Clark56356312018-02-08 14:45:18 -05002116#SeeAlso MakeFromTexture makeTextureImage
Cary Clarka560c472017-11-27 10:44:06 -05002117
2118#Method ##
2119
2120# ------------------------------------------------------------------------------
2121
2122#Enum LegacyBitmapMode
Cary Clark56356312018-02-08 14:45:18 -05002123#Deprecated soon
Cary Clarka560c472017-11-27 10:44:06 -05002124#Code
2125 enum LegacyBitmapMode {
2126 kRO_LegacyBitmapMode,
Cary Clarka560c472017-11-27 10:44:06 -05002127 };
2128##
2129
Cary Clarka560c472017-11-27 10:44:06 -05002130#Const kRO_LegacyBitmapMode 0
Cary Clark682c58d2018-05-16 07:07:07 -04002131#Line # returned bitmap is read-only and immutable ##
Cary Clarka560c472017-11-27 10:44:06 -05002132##
Cary Clarka560c472017-11-27 10:44:06 -05002133
2134#Enum ##
2135
2136# ------------------------------------------------------------------------------
2137
Cary Clark56356312018-02-08 14:45:18 -05002138#Method bool asLegacyBitmap(SkBitmap* bitmap, LegacyBitmapMode legacyBitmapMode = kRO_LegacyBitmapMode) const
Cary Clark4855f782018-02-06 09:41:53 -05002139#In Constructor
2140#Line # returns as Raster_Bitmap ##
Cary Clarkac47b882018-01-11 10:35:44 -05002141Creates raster Bitmap with same pixels as Image. If legacyBitmapMode is
2142kRO_LegacyBitmapMode, returned bitmap is read-only and immutable.
2143Returns true if Bitmap is stored in bitmap. Returns false and resets bitmap if
2144Bitmap write did not succeed.
Cary Clarka560c472017-11-27 10:44:06 -05002145
Cary Clark3cd22cc2017-12-01 11:49:58 -05002146#Param bitmap storage for legacy Bitmap ##
Cary Clark56356312018-02-08 14:45:18 -05002147#Param legacyBitmapMode to be deprecated ##
Cary Clarka560c472017-11-27 10:44:06 -05002148
Cary Clark3cd22cc2017-12-01 11:49:58 -05002149#Return true if Bitmap was created ##
Cary Clarka560c472017-11-27 10:44:06 -05002150
Cary Clarkae957c42018-06-07 17:07:17 -04002151#Example
Cary Clark56356312018-02-08 14:45:18 -05002152#Image 4
2153#Platform gpu
Brian Salomon67f85842018-02-09 08:50:22 -05002154 SkBitmap bitImage;
2155 if (image->asLegacyBitmap(&bitImage, SkImage::kRO_LegacyBitmapMode)) {
2156 canvas->drawBitmap(bitImage, 0, 0);
2157 }
2158 GrContext* grContext = canvas->getGrContext();
2159 if (!grContext) {
2160 return;
2161 }
2162 sk_sp<SkImage> textureImage(SkImage::MakeFromTexture(grContext, backEndTexture,
Cary Clarkae957c42018-06-07 17:07:17 -04002163 kTopLeft_GrSurfaceOrigin, kRGBA_8888_SkColorType,
2164 kOpaque_SkAlphaType, nullptr));
Brian Salomon67f85842018-02-09 08:50:22 -05002165 canvas->drawImage(textureImage, 45, 45);
2166 if (textureImage->asLegacyBitmap(&bitImage, SkImage::kRO_LegacyBitmapMode)) {
2167 canvas->drawBitmap(bitImage, 90, 90);
2168 }
Cary Clarka560c472017-11-27 10:44:06 -05002169##
2170
Cary Clark56356312018-02-08 14:45:18 -05002171#SeeAlso MakeRasterData makeRasterImage makeNonTextureImage
Cary Clarka560c472017-11-27 10:44:06 -05002172
2173#Method ##
2174
2175# ------------------------------------------------------------------------------
2176
2177#Method bool isLazyGenerated() const
Cary Clark4855f782018-02-06 09:41:53 -05002178#In Property
2179#Line # returns if Image is created as needed ##
Cary Clarka560c472017-11-27 10:44:06 -05002180Returns true if Image is backed by an image-generator or other service that creates
2181and caches its pixels or texture on-demand.
2182
Cary Clark2f466242017-12-11 16:03:17 -05002183#Return true if Image is created as needed ##
Cary Clarka560c472017-11-27 10:44:06 -05002184
2185#Example
Cary Clark2f466242017-12-11 16:03:17 -05002186#Height 80
2187#Function
2188class TestImageGenerator : public SkImageGenerator {
2189public:
2190 TestImageGenerator() : SkImageGenerator(SkImageInfo::MakeN32Premul(10, 10)) {}
2191 ~TestImageGenerator() override {}
2192protected:
2193 bool onGetPixels(const SkImageInfo& info, void* pixelPtr, size_t rowBytes,
2194 const Options& options) override {
2195 SkPMColor* pixels = static_cast<SkPMColor*>(pixelPtr);
2196 for (int y = 0; y < info.height(); ++y) {
2197 for (int x = 0; x < info.width(); ++x) {
2198 pixels[y * info.width() + x] = 0xff223344 + y * 0x000C0811;
2199 }
2200 }
2201 return true;
2202 }
2203};
2204##
2205void draw(SkCanvas* canvas) {
2206 auto gen = std::unique_ptr<TestImageGenerator>(new TestImageGenerator());
2207 sk_sp<SkImage> image(SkImage::MakeFromGenerator(std::move(gen)));
2208 SkString lazy(image->isLazyGenerated() ? "is lazy" : "not lazy");
2209 canvas->scale(8, 8);
2210 canvas->drawImage(image, 0, 0, nullptr);
2211 SkPaint paint;
2212 paint.setTextSize(4);
2213 canvas->drawString(lazy, 2, 5, paint);
2214}
Cary Clarka560c472017-11-27 10:44:06 -05002215##
2216
Cary Clarkf5404bb2018-01-05 12:10:09 -05002217#Example
2218#Image 5
2219#Platform gpu
2220void draw(SkCanvas* canvas) {
2221 auto drawImage = [=](sk_sp<SkImage> image, const char* label) -> void {
2222 if (nullptr == image) {
2223 return;
2224 }
2225 SkPaint paint;
2226 paint.setAntiAlias(true);
2227 paint.setTextAlign(SkPaint::kCenter_Align);
2228 canvas->drawImage(image, 0, 0);
2229 canvas->drawString(label, image->width() / 2, image->height() / 4, paint);
2230 canvas->drawString(
2231 image->isLazyGenerated() ? "is lazily generated" : "not lazily generated",
2232 image->width() / 2, image->height() * 3 / 4, paint);
2233 };
2234 sk_sp<SkImage> bitmapImage(SkImage::MakeFromBitmap(source));
2235 sk_sp<SkImage> textureImage(SkImage::MakeFromTexture(canvas->getGrContext(), backEndTexture,
Cary Clarkae957c42018-06-07 17:07:17 -04002236 kTopLeft_GrSurfaceOrigin, kRGBA_8888_SkColorType,
2237 kOpaque_SkAlphaType, nullptr));
Cary Clarkf5404bb2018-01-05 12:10:09 -05002238 drawImage(image, "image");
2239 canvas->translate(image->width(), 0);
2240 drawImage(bitmapImage, "source");
2241 canvas->translate(-image->width(), image->height());
2242 drawImage(textureImage, "backEndTexture");
2243}
2244##
2245
Cary Clarkac47b882018-01-11 10:35:44 -05002246#SeeAlso isTextureBacked MakeNonTextureImage
Cary Clarka560c472017-11-27 10:44:06 -05002247
2248#Method ##
2249
2250# ------------------------------------------------------------------------------
2251
Cary Clarke80cd442018-07-17 13:19:56 -04002252#Method sk_sp<SkImage> makeColorSpace(sk_sp<SkColorSpace> target) const
Cary Clark4855f782018-02-06 09:41:53 -05002253#In Constructor
2254#Line # creates Image matching Color_Space if possible ##
Cary Clarka560c472017-11-27 10:44:06 -05002255
Cary Clarkac47b882018-01-11 10:35:44 -05002256Creates Image in target Color_Space.
2257Returns nullptr if Image could not be created.
Cary Clarka560c472017-11-27 10:44:06 -05002258
Cary Clarkac47b882018-01-11 10:35:44 -05002259Returns original Image if it is in target Color_Space.
2260Otherwise, converts pixels from Image Color_Space to target Color_Space.
2261If Image colorSpace returns nullptr, Image Color_Space is assumed to be sRGB.
2262
Cary Clarkac47b882018-01-11 10:35:44 -05002263#Param target Color_Space describing color range of returned Image ##
Cary Clarka560c472017-11-27 10:44:06 -05002264
Cary Clarkac47b882018-01-11 10:35:44 -05002265#Return created Image in target Color_Space ##
2266
2267#Example
2268#Image 5
2269#Set sRGB
2270 sk_sp<SkColorSpace> normalColorSpace = SkColorSpace::MakeRGB(
2271 SkColorSpace::kSRGB_RenderTargetGamma, SkColorSpace::kSRGB_Gamut);
2272 sk_sp<SkColorSpace> wackyColorSpace = normalColorSpace->makeColorSpin();
2273 for (auto colorSpace : { normalColorSpace, wackyColorSpace } ) {
Cary Clarkc3c1c312018-07-18 09:25:15 -04002274 sk_sp<SkImage> colorSpaced = image->makeColorSpace(colorSpace);
2275 canvas->drawImage(colorSpaced, 0, 0);
2276 canvas->translate(128, 0);
Cary Clarkac47b882018-01-11 10:35:44 -05002277 }
2278##
2279
2280#SeeAlso MakeFromPixture MakeFromTexture
Cary Clarka560c472017-11-27 10:44:06 -05002281
2282#Method ##
2283
2284#Class SkImage ##
2285
2286#Topic Image ##