1/*
2 * Copyright 2012 Google Inc.
3 *
4 * Use of this source code is governed by a BSD-style license that can be
5 * found in the LICENSE file.
6 */
7
8#ifndef SkImage_DEFINED
9#define SkImage_DEFINED
10
11#include "GrTypes.h"
12#include "SkFilterQuality.h"
13#include "SkImageInfo.h"
14#include "SkImageEncoder.h"
15#include "SkRefCnt.h"
16#include "SkScalar.h"
17#include "SkShader.h"
18
19#if defined(SK_BUILD_FOR_ANDROID) && __ANDROID_API__ >= 26
20#include <android/hardware_buffer.h>
21#endif
22
23class SkData;
24class SkCanvas;
25class SkImageFilter;
26class SkImageGenerator;
27class SkPaint;
28class SkPicture;
29class SkString;
30class SkSurface;
31class GrBackendTexture;
32class GrContext;
33class GrContextThreadSafeProxy;
34class GrTexture;
35
36/** \class SkImage
37    SkImage describes a two dimensional array of pixels to draw. The pixels may be
38    decoded in a raster bitmap, encoded in a SkPicture or compressed data stream,
39    or located in GPU memory as a GPU texture.
40
41    SkImage cannot be modified after it is created. SkImage may allocate additional
42    storage as needed; for instance, an encoded SkImage may decode when drawn.
43
44    SkImage width and height are greater than zero. Creating an SkImage with zero width
45    or height returns SkImage equal to nullptr.
46
47    SkImage may be created from SkBitmap, SkPixmap, SkSurface, SkPicture, encoded streams,
48    GPU texture, YUV_ColorSpace data, or hardware buffer. Encoded streams supported
49    include BMP, GIF, HEIF, ICO, JPEG, PNG, WBMP, WebP. Supported encoding details
50    vary with platform.
51*/
52class SK_API SkImage : public SkRefCnt {
53public:
54    typedef SkImageInfo Info;
55    typedef void* ReleaseContext;
56
57    /** Creates SkImage from SkPixmap and copy of pixels. Since pixels are copied, SkPixmap
58        pixels may be modified or deleted without affecting SkImage.
59
60        SkImage is returned if SkPixmap is valid. Valid SkPixmap parameters include:
61        dimensions are greater than zero;
62        each dimension fits in 29 bits;
63        SkColorType and SkAlphaType are valid, and SkColorType is not kUnknown_SkColorType;
64        row bytes are large enough to hold one row of pixels;
65        pixel address is not nullptr.
66
67        @param pixmap  SkImageInfo, pixel address, and row bytes
68        @return        copy of SkPixmap pixels, or nullptr
69    */
70    static sk_sp<SkImage> MakeRasterCopy(const SkPixmap& pixmap);
71
72    /** Creates SkImage from SkImageInfo, sharing pixels.
73
74        SkImage is returned if SkImageInfo is valid. Valid SkImageInfo parameters include:
75        dimensions are greater than zero;
76        each dimension fits in 29 bits;
77        SkColorType and SkAlphaType are valid, and SkColorType is not kUnknown_SkColorType;
78        rowBytes are large enough to hold one row of pixels;
79        pixels is not nullptr, and contains enough data for SkImage.
80
81        @param info      contains width, height, SkAlphaType, SkColorType, SkColorSpace
82        @param pixels    address or pixel storage
83        @param rowBytes  size of pixel row or larger
84        @return          SkImage sharing pixels, or nullptr
85    */
86    static sk_sp<SkImage> MakeRasterData(const Info& info, sk_sp<SkData> pixels, size_t rowBytes);
87
88    typedef void (*RasterReleaseProc)(const void* pixels, ReleaseContext);
89
90    /** Creates SkImage from pixmap, sharing SkPixmap pixels. Pixels must remain valid and
91        unchanged until rasterReleaseProc is called. rasterReleaseProc is passed
92        releaseContext when SkImage is deleted or no longer refers to pixmap pixels.
93
94        Pass nullptr for rasterReleaseProc to share SkPixmap without requiring a callback
95        when SkImage is released. Pass nullptr for releaseContext if rasterReleaseProc
96        does not require state.
97
98        SkImage is returned if pixmap is valid. Valid SkPixmap parameters include:
99        dimensions are greater than zero;
100        each dimension fits in 29 bits;
101        SkColorType and SkAlphaType are valid, and SkColorType is not kUnknown_SkColorType;
102        row bytes are large enough to hold one row of pixels;
103        pixel address is not nullptr.
104
105        @param pixmap             SkImageInfo, pixel address, and row bytes
106        @param rasterReleaseProc  function called when pixels can be released; or nullptr
107        @param releaseContext     state passed to rasterReleaseProc; or nullptr
108        @return                   SkImage sharing pixmap
109    */
110    static sk_sp<SkImage> MakeFromRaster(const SkPixmap& pixmap,
111                                         RasterReleaseProc rasterReleaseProc,
112                                         ReleaseContext releaseContext);
113
114    /** Creates SkImage from bitmap, sharing or copying bitmap pixels. If the bitmap
115        is marked immutable, and its pixel memory is shareable, it may be shared
116        instead of copied.
117
118        SkImage is returned if bitmap is valid. Valid SkBitmap parameters include:
119        dimensions are greater than zero;
120        each dimension fits in 29 bits;
121        SkColorType and SkAlphaType are valid, and SkColorType is not kUnknown_SkColorType;
122        row bytes are large enough to hold one row of pixels;
123        pixel address is not nullptr.
124
125        @param bitmap  SkImageInfo, row bytes, and pixels
126        @return        created SkImage, or nullptr
127    */
128    static sk_sp<SkImage> MakeFromBitmap(const SkBitmap& bitmap);
129
130    /** Creates SkImage from data returned by imageGenerator. Generated data is owned by SkImage and may not
131        be shared or accessed.
132
133        subset allows selecting a portion of the full image. Pass nullptr to select the entire image;
134        otherwise, subset must be contained by image bounds.
135
136        SkImage is returned if generator data is valid. Valid data parameters vary by type of data
137        and platform.
138
139        imageGenerator may wrap SkPicture data, codec data, or custom data.
140
141        @param imageGenerator  stock or custom routines to retrieve SkImage
142        @param subset          bounds of returned SkImage; may be nullptr
143        @return                created SkImage, or nullptr
144    */
145    static sk_sp<SkImage> MakeFromGenerator(std::unique_ptr<SkImageGenerator> imageGenerator,
146                                            const SkIRect* subset = nullptr);
147
148    /** Creates SkImage from encoded data.
149        subset allows selecting a portion of the full image. Pass nullptr to select the entire image;
150        otherwise, subset must be contained by image bounds.
151
152        SkImage is returned if format of the encoded data is recognized and supported.
153        Recognized formats vary by platform.
154
155        @param encoded  data of SkImage to decode
156        @param subset   bounds of returned SkImage; may be nullptr
157        @return         created SkImage, or nullptr
158    */
159    static sk_sp<SkImage> MakeFromEncoded(sk_sp<SkData> encoded, const SkIRect* subset = nullptr);
160
161    typedef void (*TextureReleaseProc)(ReleaseContext releaseContext);
162
163    /** Deprecated.
164    */
165    static sk_sp<SkImage> MakeFromTexture(GrContext* context,
166                                          const GrBackendTexture& backendTexture,
167                                          GrSurfaceOrigin origin,
168                                          SkAlphaType alphaType,
169                                          sk_sp<SkColorSpace> colorSpace) {
170        return MakeFromTexture(context, backendTexture, origin, alphaType, colorSpace, nullptr,
171                               nullptr);
172    }
173
174    /** Deprecated.
175    */
176    static sk_sp<SkImage> MakeFromTexture(GrContext* context,
177                                          const GrBackendTexture& backendTexture,
178                                          GrSurfaceOrigin origin,
179                                          SkAlphaType alphaType,
180                                          sk_sp<SkColorSpace> colorSpace,
181                                          TextureReleaseProc textureReleaseProc,
182                                          ReleaseContext releaseContext);
183
184    /** Creates SkImage from GPU texture associated with context. Caller is responsible for
185        managing the lifetime of GPU texture.
186
187        SkImage is returned if format of backendTexture is recognized and supported.
188        Recognized formats vary by GPU back-end.
189
190        @param context         GPU context
191        @param backendTexture  texture residing on GPU
192        @param origin          one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
193        @param colorType       one of: kUnknown_SkColorType, kAlpha_8_SkColorType,
194                               kRGB_565_SkColorType, kARGB_4444_SkColorType,
195                               kRGBA_8888_SkColorType, kBGRA_8888_SkColorType,
196                               kGray_8_SkColorType, kRGBA_F16_SkColorType
197        @param alphaType       one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType,
198                               kPremul_SkAlphaType, kUnpremul_SkAlphaType
199        @param colorSpace      range of colors; may be nullptr
200        @return                created SkImage, or nullptr
201    */
202    static sk_sp<SkImage> MakeFromTexture(GrContext* context,
203                                          const GrBackendTexture& backendTexture,
204                                          GrSurfaceOrigin origin,
205                                          SkColorType colorType,
206                                          SkAlphaType alphaType,
207                                          sk_sp<SkColorSpace> colorSpace) {
208        return MakeFromTexture(context, backendTexture, origin, colorType, alphaType, colorSpace,
209                               nullptr, nullptr);
210    }
211
212    /** Creates SkImage from GPU texture associated with context. GPU texture must stay
213        valid and unchanged until textureReleaseProc is called. textureReleaseProc is
214        passed releaseContext when SkImage is deleted or no longer refers to texture.
215
216        SkImage is returned if format of backendTexture is recognized and supported.
217        Recognized formats vary by GPU back-end.
218
219        @param context             GPU context
220        @param backendTexture      texture residing on GPU
221        @param origin              one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
222        @param colorType           one of: kUnknown_SkColorType, kAlpha_8_SkColorType,
223                                   kRGB_565_SkColorType, kARGB_4444_SkColorType,
224                                   kRGBA_8888_SkColorType, kBGRA_8888_SkColorType,
225                                   kGray_8_SkColorType, kRGBA_F16_SkColorType
226        @param alphaType           one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType,
227                                   kPremul_SkAlphaType, kUnpremul_SkAlphaType
228        @param colorSpace          range of colors; may be nullptr
229        @param textureReleaseProc  function called when texture can be released
230        @param releaseContext      state passed to textureReleaseProc
231        @return                    created SkImage, or nullptr
232    */
233    static sk_sp<SkImage> MakeFromTexture(GrContext* context,
234                                          const GrBackendTexture& backendTexture,
235                                          GrSurfaceOrigin origin,
236                                          SkColorType colorType,
237                                          SkAlphaType alphaType,
238                                          sk_sp<SkColorSpace> colorSpace,
239                                          TextureReleaseProc textureReleaseProc,
240                                          ReleaseContext releaseContext);
241
242    /** Creates SkImage from encoded data. SkImage is uploaded to GPU back-end using context.
243
244        Created SkImage is available to other GPU contexts, and is available across thread
245        boundaries. All contexts must be in the same GPU_Share_Group, or otherwise
246        share resources.
247
248        When SkImage is no longer referenced, context releases texture memory
249        asynchronously.
250
251        GrBackendTexture decoded from data is uploaded to match SkSurface created with
252        dstColorSpace. SkColorSpace of SkImage is determined by encoded data.
253
254        SkImage is returned if format of data is recognized and supported, and if context
255        supports moving resources. Recognized formats vary by platform and GPU back-end.
256
257        SkImage is returned using MakeFromEncoded() if context is nullptr or does not support
258        moving resources between contexts.
259
260        @param context        GPU context
261        @param data           SkImage to decode
262        @param buildMips      create SkImage as Mip_Map if true
263        @param dstColorSpace  range of colors of matching SkSurface on GPU
264        @return               created SkImage, or nullptr
265    */
266    static sk_sp<SkImage> MakeCrossContextFromEncoded(GrContext* context, sk_sp<SkData> data,
267                                                      bool buildMips, SkColorSpace* dstColorSpace);
268
269    /** Creates SkImage from pixmap. SkImage is uploaded to GPU back-end using context.
270
271        Created SkImage is available to other GPU contexts, and is available across thread
272        boundaries. All contexts must be in the same GPU_Share_Group, or otherwise
273        share resources.
274
275        When SkImage is no longer referenced, context releases texture memory
276        asynchronously.
277
278        GrBackendTexture created from pixmap is uploaded to match SkSurface created with
279        dstColorSpace. SkColorSpace of SkImage is determined by pixmap.colorSpace().
280
281        SkImage is returned referring to GPU back-end if context is not nullptr,
282        format of data is recognized and supported, and if context supports moving
283        resources between contexts. Otherwise, pixmap pixel data is copied and SkImage
284        as returned in raster format if possible; nullptr may be returned.
285        Recognized GPU formats vary by platform and GPU back-end.
286
287        @param context        GPU context
288        @param pixmap         SkImageInfo, pixel address, and row bytes
289        @param buildMips      create SkImage as Mip_Map if true
290        @param dstColorSpace  range of colors of matching SkSurface on GPU
291        @return               created SkImage, or nullptr
292    */
293    static sk_sp<SkImage> MakeCrossContextFromPixmap(GrContext* context, const SkPixmap& pixmap,
294                                                     bool buildMips, SkColorSpace* dstColorSpace);
295
296    /** Deprecated.
297    */
298    static sk_sp<SkImage> MakeFromAdoptedTexture(GrContext* context,
299                                                 const GrBackendTexture& backendTexture,
300                                                 GrSurfaceOrigin surfaceOrigin,
301                                                 SkAlphaType alphaType = kPremul_SkAlphaType,
302                                                 sk_sp<SkColorSpace> colorSpace = nullptr);
303
304    /** Creates SkImage from backendTexture associated with context. backendTexture and
305        returned SkImage are managed internally, and are released when no longer needed.
306
307        SkImage is returned if format of backendTexture is recognized and supported.
308        Recognized formats vary by GPU back-end.
309
310        @param context         GPU context
311        @param backendTexture  texture residing on GPU
312        @param surfaceOrigin   one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
313        @param colorType       one of: kUnknown_SkColorType, kAlpha_8_SkColorType,
314                               kRGB_565_SkColorType, kARGB_4444_SkColorType,
315                               kRGBA_8888_SkColorType, kBGRA_8888_SkColorType,
316                               kGray_8_SkColorType, kRGBA_F16_SkColorType
317        @param alphaType       one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType,
318                               kPremul_SkAlphaType, kUnpremul_SkAlphaType
319        @param colorSpace      range of colors; may be nullptr
320        @return                created SkImage, or nullptr
321    */
322    static sk_sp<SkImage> MakeFromAdoptedTexture(GrContext* context,
323                                                 const GrBackendTexture& backendTexture,
324                                                 GrSurfaceOrigin surfaceOrigin,
325                                                 SkColorType colorType,
326                                                 SkAlphaType alphaType = kPremul_SkAlphaType,
327                                                 sk_sp<SkColorSpace> colorSpace = nullptr);
328
329    /** Creates SkImage from copy of yuvTextureHandles, an array of textures on GPU.
330        yuvTextureHandles contain pixels for YUV planes of SkImage.
331        yuvSizes contain dimensions for each pixel plane. Dimensions must be greater than
332        zero but may differ from plane to plane. Returned SkImage has the dimensions
333        yuvSizes[0]. yuvColorSpace describes how YUV colors convert to RGB colors.
334
335        @param context            GPU context
336        @param yuvColorSpace      one of: kJPEG_SkYUVColorSpace, kRec601_SkYUVColorSpace,
337                                  kRec709_SkYUVColorSpace
338        @param yuvTextureHandles  array of YUV textures on GPU
339        @param yuvSizes           dimensions of YUV textures
340        @param surfaceOrigin      one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
341        @param colorSpace         range of colors; may be nullptr
342        @return                   created SkImage, or nullptr
343    */
344    static sk_sp<SkImage> MakeFromYUVTexturesCopy(GrContext* context, SkYUVColorSpace yuvColorSpace,
345                                                  const GrBackendObject yuvTextureHandles[3],
346                                                  const SkISize yuvSizes[3],
347                                                  GrSurfaceOrigin surfaceOrigin,
348                                                  sk_sp<SkColorSpace> colorSpace = nullptr);
349
350    /** Creates SkImage from copy of nv12TextureHandles, an array of textures on GPU.
351        nv12TextureHandles[0] contains pixels for YUV_Component_Y plane.
352        nv12TextureHandles[1] contains pixels for YUV_Component_U plane,
353        followed by pixels for YUV_Component_V plane.
354        nv12Sizes contain dimensions for each pixel plane. Dimensions must be greater than
355        zero but may differ from plane to plane. Returned SkImage has the dimensions
356        nv12Sizes[0]. yuvColorSpace describes how YUV colors convert to RGB colors.
357
358        @param context             GPU context
359        @param yuvColorSpace       one of: kJPEG_SkYUVColorSpace, kRec601_SkYUVColorSpace,
360                                   kRec709_SkYUVColorSpace
361        @param nv12TextureHandles  array of YUV textures on GPU
362        @param nv12Sizes           dimensions of YUV textures
363        @param surfaceOrigin       one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
364        @param colorSpace          range of colors; may be nullptr
365        @return                    created SkImage, or nullptr
366    */
367    static sk_sp<SkImage> MakeFromNV12TexturesCopy(GrContext* context,
368                                                   SkYUVColorSpace yuvColorSpace,
369                                                   const GrBackendObject nv12TextureHandles[2],
370                                                   const SkISize nv12Sizes[2],
371                                                   GrSurfaceOrigin surfaceOrigin,
372                                                   sk_sp<SkColorSpace> colorSpace = nullptr);
373
374    /** Creates SkImage from copy of yuvTextureHandles, an array of textures on GPU.
375        yuvTextureHandles contain pixels for YUV planes of SkImage.
376        yuvSizes contain dimensions for each pixel plane. Dimensions must be greater than
377        zero but may differ from plane to plane. Returned SkImage has the dimensions
378        yuvSizes[0]. yuvColorSpace describes how YUV colors convert to RGB colors.
379
380        @param context            GPU context
381        @param yuvColorSpace      one of: kJPEG_SkYUVColorSpace, kRec601_SkYUVColorSpace,
382                                  kRec709_SkYUVColorSpace
383        @param yuvTextureHandles  array of YUV textures on GPU
384        @param yuvSizes           dimensions of YUV textures
385        @param surfaceOrigin      one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
386        @param colorSpace         range of colors; may be nullptr
387        @return                   created SkImage, or nullptr
388    */
389    static sk_sp<SkImage> MakeFromYUVTexturesCopy(GrContext* context, SkYUVColorSpace yuvColorSpace,
390                                                  const GrBackendTexture yuvTextureHandles[3],
391                                                  const SkISize yuvSizes[3],
392                                                  GrSurfaceOrigin surfaceOrigin,
393                                                  sk_sp<SkColorSpace> colorSpace = nullptr);
394
395    /** Creates SkImage from copy of nv12TextureHandles, an array of textures on GPU.
396        nv12TextureHandles[0] contains pixels for YUV_Component_Y plane.
397        nv12TextureHandles[1] contains pixels for YUV_Component_U plane,
398        followed by pixels for YUV_Component_V plane.
399        nv12Sizes contain dimensions for each pixel plane. Dimensions must be greater than
400        zero but may differ from plane to plane. Returned SkImage has the dimensions
401        nv12Sizes[0]. yuvColorSpace describes how YUV colors convert to RGB colors.
402
403        @param context             GPU context
404        @param yuvColorSpace       one of: kJPEG_SkYUVColorSpace, kRec601_SkYUVColorSpace,
405                                   kRec709_SkYUVColorSpace
406        @param nv12TextureHandles  array of YUV textures on GPU
407        @param nv12Sizes           dimensions of YUV textures
408        @param surfaceOrigin       one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
409        @param colorSpace          range of colors; may be nullptr
410        @return                    created SkImage, or nullptr
411    */
412    static sk_sp<SkImage> MakeFromNV12TexturesCopy(GrContext* context,
413                                                   SkYUVColorSpace yuvColorSpace,
414                                                   const GrBackendTexture nv12TextureHandles[2],
415                                                   const SkISize nv12Sizes[2],
416                                                   GrSurfaceOrigin surfaceOrigin,
417                                                   sk_sp<SkColorSpace> colorSpace = nullptr);
418
419    enum class BitDepth {
420        kU8,  //!< Use 8 bits per ARGB component using unsigned integer format.
421        kF16, //!< Use 16 bits per ARGB component using half-precision floating point format.
422    };
423
424    /** Creates SkImage from picture. Returned SkImage width and height are set by dimensions.
425        SkImage draws picture with matrix and paint, set to bitDepth and colorSpace.
426
427        If matrix is nullptr, draws with identity SkMatrix. If paint is nullptr, draws
428        with default SkPaint. colorSpace may be nullptr.
429
430        @param picture     stream of drawing commands
431        @param dimensions  width and height
432        @param matrix      SkMatrix to rotate, scale, translate, and so on; may be nullptr
433        @param paint       SkPaint to apply transparency, filtering, and so on; may be nullptr
434        @param bitDepth    8 bit integer or 16 bit float: per component
435        @param colorSpace  range of colors; may be nullptr
436        @return            created SkImage, or nullptr
437    */
438    static sk_sp<SkImage> MakeFromPicture(sk_sp<SkPicture> picture, const SkISize& dimensions,
439                                          const SkMatrix* matrix, const SkPaint* paint,
440                                          BitDepth bitDepth,
441                                          sk_sp<SkColorSpace> colorSpace);
442
443#if defined(SK_BUILD_FOR_ANDROID) && __ANDROID_API__ >= 26
444    /** (see skbug.com/7447)
445        Creates SkImage from Android hardware buffer.
446        Returned SkImage takes a reference on the buffer.
447
448        Only available on Android, when __ANDROID_API__ is defined to be 26 or greater.
449
450        @param hardwareBuffer  AHardwareBuffer Android hardware buffer
451        @param alphaType       one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType,
452                               kPremul_SkAlphaType, kUnpremul_SkAlphaType
453        @param colorSpace      range of colors; may be nullptr
454        @return                created SkImage, or nullptr
455    */
456    static sk_sp<SkImage> MakeFromAHardwareBuffer(AHardwareBuffer* hardwareBuffer,
457                                                 SkAlphaType alphaType = kPremul_SkAlphaType,
458                                                 sk_sp<SkColorSpace> colorSpace = nullptr);
459#endif
460
461    /** Returns pixel count in each row.
462
463        @return  pixel width in SkImage
464    */
465    int width() const { return fWidth; }
466
467    /** Returns pixel row count.
468
469        @return  pixel height in SkImage
470    */
471    int height() const { return fHeight; }
472
473    /** Returns SkISize { width(), height() }.
474
475        @return  integral size of width() and height()
476    */
477    SkISize dimensions() const { return SkISize::Make(fWidth, fHeight); }
478
479    /** Returns SkIRect { 0, 0, width(), height() }.
480
481        @return  integral rectangle from origin to width() and height()
482    */
483    SkIRect bounds() const { return SkIRect::MakeWH(fWidth, fHeight); }
484
485    /** Returns value unique to image. SkImage contents cannot change after SkImage is
486        created. Any operation to create a new SkImage will receive generate a new
487        unique number.
488
489        @return  unique identifier
490    */
491    uint32_t uniqueID() const { return fUniqueID; }
492
493    /** Returns SkAlphaType, one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType,
494        kPremul_SkAlphaType, kUnpremul_SkAlphaType.
495
496        SkAlphaType returned was a parameter to an SkImage constructor,
497        or was parsed from encoded data.
498
499        @return  SkAlphaType in SkImage
500    */
501    SkAlphaType alphaType() const;
502
503    /** Returns SkColorSpace, the range of colors, associated with SkImage.  The
504        reference count of SkColorSpace is unchanged. The returned SkColorSpace is
505        immutable.
506
507        SkColorSpace returned was passed to an SkImage constructor,
508        or was parsed from encoded data. SkColorSpace returned may be ignored when SkImage
509        is drawn, depending on the capabilities of the SkSurface receiving the drawing.
510
511        @return  SkColorSpace in SkImage, or nullptr
512    */
513    SkColorSpace* colorSpace() const;
514
515    /** Returns a smart pointer to SkColorSpace, the range of colors, associated with
516        SkImage.  The smart pointer tracks the number of objects sharing this
517        SkColorSpace reference so the memory is released when the owners destruct.
518
519        The returned SkColorSpace is immutable.
520
521        SkColorSpace returned was passed to an SkImage constructor,
522        or was parsed from encoded data. SkColorSpace returned may be ignored when SkImage
523        is drawn, depending on the capabilities of the SkSurface receiving the drawing.
524
525        @return  SkColorSpace in SkImage, or nullptr, wrapped in a smart pointer
526    */
527    sk_sp<SkColorSpace> refColorSpace() const;
528
529    /** Returns true if SkImage pixels represent transparency only. If true, each pixel
530        is packed in 8 bits as defined by kAlpha_8_SkColorType.
531
532        @return  true if pixels represent a transparency mask
533    */
534    bool isAlphaOnly() const;
535
536    /** Returns true if pixels ignore their alpha value and are treated as fully opaque.
537
538        @return  true if SkAlphaType is kOpaque_SkAlphaType
539    */
540    bool isOpaque() const { return SkAlphaTypeIsOpaque(this->alphaType()); }
541
542    /** Creates SkShader from SkImage. SkShader dimensions are taken from SkImage. SkShader uses
543        SkShader::TileMode rules to fill drawn area outside SkImage. localMatrix permits
544        transforming SkImage before SkCanvas matrix is applied.
545
546        @param tileMode1    tiling in x, one of: SkShader::kClamp_TileMode, SkShader::kRepeat_TileMode,
547                            SkShader::kMirror_TileMode
548        @param tileMode2    tiling in y, one of: SkShader::kClamp_TileMode, SkShader::kRepeat_TileMode,
549                            SkShader::kMirror_TileMode
550        @param localMatrix  SkImage transformation, or nullptr
551        @return             SkShader containing SkImage
552    */
553    sk_sp<SkShader> makeShader(SkShader::TileMode tileMode1, SkShader::TileMode tileMode2,
554                               const SkMatrix* localMatrix = nullptr) const;
555
556    /** Creates SkShader from SkImage. SkShader dimensions are taken from SkImage. SkShader uses
557        SkShader::kClamp_TileMode to fill drawn area outside SkImage. localMatrix permits
558        transforming SkImage before SkCanvas matrix is applied.
559
560        @param localMatrix  SkImage transformation, or nullptr
561        @return             SkShader containing SkImage
562    */
563    sk_sp<SkShader> makeShader(const SkMatrix* localMatrix = nullptr) const {
564        return this->makeShader(SkShader::kClamp_TileMode, SkShader::kClamp_TileMode, localMatrix);
565    }
566
567    /** Copies SkImage pixel address, row bytes, and SkImageInfo to pixmap, if address
568        is available, and returns true. If pixel address is not available, return
569        false and leave pixmap unchanged.
570
571        @param pixmap  storage for pixel state if pixels are readable; otherwise, ignored
572        @return        true if SkImage has direct access to pixels
573    */
574    bool peekPixels(SkPixmap* pixmap) const;
575
576    /** Deprecated.
577    */
578    GrTexture* getTexture() const;
579
580    /** Returns true the contents of SkImage was created on or uploaded to GPU memory,
581        and is available as a GPU texture.
582
583        @return  true if SkImage is a GPU texture
584    */
585    bool isTextureBacked() const;
586
587    /** Returns true if SkImage can be drawn on either raster surface or GPU surface.
588        If context is nullptr, tests if SkImage draws on raster surface;
589        otherwise, tests if SkImage draws on GPU surface associated with context.
590
591        SkImage backed by GPU texture may become invalid if associated GrContext is
592        invalid. lazy image may be invalid and may not draw to raster surface or
593        GPU surface or both.
594
595        @param context  GPU context
596        @return         true if SkImage can be drawn
597    */
598    bool isValid(GrContext* context) const;
599
600    /** Retrieves the back-end API handle of texture. If flushPendingGrContextIO is true,
601        complete deferred I/O operations.
602
603        If origin in not nullptr, copies location of content drawn into SkImage.
604
605        @param flushPendingGrContextIO  flag to flush outstanding requests
606        @param origin                   storage for one of: kTopLeft_GrSurfaceOrigin,
607                                        kBottomLeft_GrSurfaceOrigin; or nullptr
608        @return                         back-end API texture handle, or nullptr
609    */
610    GrBackendObject getTextureHandle(bool flushPendingGrContextIO,
611                                     GrSurfaceOrigin* origin = nullptr) const;
612
613    /** \enum SkImage::CachingHint
614        CachingHint selects whether Skia may internally cache SkBitmap generated by
615        decoding SkImage, or by copying SkImage from GPU to CPU. The default behavior
616        allows caching SkBitmap.
617
618        Choose kDisallow_CachingHint if SkImage pixels are to be used only once, or
619        if SkImage pixels reside in a cache outside of Skia, or to reduce memory pressure.
620
621        Choosing kAllow_CachingHint does not ensure that pixels will be cached.
622        SkImage pixels may not be cached if memory requirements are too large or
623        pixels are not accessible.
624    */
625    enum CachingHint {
626        kAllow_CachingHint,    //!< Allows Skia to internally cache decoded and copied pixels.
627
628        /** Disallows Skia from internally caching decoded and copied pixels. */
629        kDisallow_CachingHint,
630    };
631
632    /** Copies SkRect of pixels from SkImage to dstPixels. Copy starts at offset (srcX, srcY),
633        and does not exceed SkImage (width(), height()).
634
635        dstInfo specifies width, height, SkColorType, SkAlphaType, and SkColorSpace of
636        destination. dstRowBytes specifics the gap from one destination row to the next.
637        Returns true if pixels are copied. Returns false if:
638        - dstInfo.addr() equals nullptr
639        - dstRowBytes is less than dstInfo.minRowBytes()
640        - SkPixelRef is nullptr
641
642        Pixels are copied only if pixel conversion is possible. If SkImage SkColorType is
643        kGray_8_SkColorType, or kAlpha_8_SkColorType; dstInfo.colorType() must match.
644        If SkImage SkColorType is kGray_8_SkColorType, dstInfo.colorSpace() must match.
645        If SkImage SkAlphaType is kOpaque_SkAlphaType, dstInfo.alphaType() must
646        match. If SkImage SkColorSpace is nullptr, dstInfo.colorSpace() must match. Returns
647        false if pixel conversion is not possible.
648
649        srcX and srcY may be negative to copy only top or left of source. Returns
650        false if width() or height() is zero or negative.
651        Returns false if abs(srcX) >= Image width(), or if abs(srcY) >= Image height().
652
653        If cachingHint is kAllow_CachingHint, pixels may be retained locally.
654        If cachingHint is kDisallow_CachingHint, pixels are not added to the local cache.
655
656        @param dstInfo      destination width, height, SkColorType, SkAlphaType, SkColorSpace
657        @param dstPixels    destination pixel storage
658        @param dstRowBytes  destination row length
659        @param srcX         column index whose absolute value is less than width()
660        @param srcY         row index whose absolute value is less than height()
661        @param cachingHint  one of: kAllow_CachingHint, kDisallow_CachingHint
662        @return             true if pixels are copied to dstPixels
663    */
664    bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes,
665                    int srcX, int srcY, CachingHint cachingHint = kAllow_CachingHint) const;
666
667    /** Copies a SkRect of pixels from SkImage to dst. Copy starts at (srcX, srcY), and
668        does not exceed SkImage (width(), height()).
669
670        dst specifies width, height, SkColorType, SkAlphaType, SkColorSpace, pixel storage,
671        and row bytes of destination. dst.rowBytes() specifics the gap from one destination
672        row to the next. Returns true if pixels are copied. Returns false if:
673        - dst pixel storage equals nullptr
674        - dst.rowBytes is less than SkImageInfo::minRowBytes
675        - SkPixelRef is nullptr
676
677        Pixels are copied only if pixel conversion is possible. If SkImage SkColorType is
678        kGray_8_SkColorType, or kAlpha_8_SkColorType; dst.colorType() must match.
679        If SkImage SkColorType is kGray_8_SkColorType, dst.colorSpace() must match.
680        If SkImage SkAlphaType is kOpaque_SkAlphaType, dst.alphaType() must
681        match. If SkImage SkColorSpace is nullptr, dst.colorSpace() must match. Returns
682        false if pixel conversion is not possible.
683
684        srcX and srcY may be negative to copy only top or left of source. Returns
685        false if width() or height() is zero or negative.
686        Returns false if abs(srcX) >= Image width(), or if abs(srcY) >= Image height().
687
688        If cachingHint is kAllow_CachingHint, pixels may be retained locally.
689        If cachingHint is kDisallow_CachingHint, pixels are not added to the local cache.
690
691        @param dst          destination SkPixmap: SkImageInfo, pixels, row bytes
692        @param srcX         column index whose absolute value is less than width()
693        @param srcY         row index whose absolute value is less than height()
694        @param cachingHint  one of: kAllow_CachingHint, kDisallow_CachingHint
695        @return             true if pixels are copied to dst
696    */
697    bool readPixels(const SkPixmap& dst, int srcX, int srcY,
698                    CachingHint cachingHint = kAllow_CachingHint) const;
699
700    /** Copies SkImage to dst, scaling pixels to fit dst.width() and dst.height(), and
701        converting pixels to match dst.colorType() and dst.alphaType(). Returns true if
702        pixels are copied. Returns false if dst.addr() is nullptr, or dst.rowBytes() is
703        less than dst SkImageInfo::minRowBytes.
704
705        Pixels are copied only if pixel conversion is possible. If SkImage SkColorType is
706        kGray_8_SkColorType, or kAlpha_8_SkColorType; dst.colorType() must match.
707        If SkImage SkColorType is kGray_8_SkColorType, dst.colorSpace() must match.
708        If SkImage SkAlphaType is kOpaque_SkAlphaType, dst.alphaType() must
709        match. If SkImage SkColorSpace is nullptr, dst.colorSpace() must match. Returns
710        false if pixel conversion is not possible.
711
712        Scales the image, with filterQuality, to match dst.width() and dst.height().
713        filterQuality kNone_SkFilterQuality is fastest, typically implemented with
714        nearest neighbor filter. kLow_SkFilterQuality is typically implemented with
715        bilerp filter. kMedium_SkFilterQuality is typically implemented with
716        bilerp filter, and Filter_Quality_MipMap when size is reduced.
717        kHigh_SkFilterQuality is slowest, typically implemented with Filter_Quality_BiCubic.
718
719        If cachingHint is kAllow_CachingHint, pixels may be retained locally.
720        If cachingHint is kDisallow_CachingHint, pixels are not added to the local cache.
721
722        @param dst            destination SkPixmap: SkImageInfo, pixels, row bytes
723        @param filterQuality  one of: kNone_SkFilterQuality, kLow_SkFilterQuality,
724                              kMedium_SkFilterQuality, kHigh_SkFilterQuality
725        @param cachingHint    one of: kAllow_CachingHint, kDisallow_CachingHint
726        @return               true if pixels are scaled to fit dst
727    */
728    bool scalePixels(const SkPixmap& dst, SkFilterQuality filterQuality,
729                     CachingHint cachingHint = kAllow_CachingHint) const;
730
731    /** Encodes SkImage pixels, returning result as SkData.
732
733        Returns nullptr if encoding fails, or if encodedImageFormat is not supported.
734
735        SkImage encoding in a format requires both building with one or more of:
736        SK_HAS_JPEG_LIBRARY, SK_HAS_PNG_LIBRARY, SK_HAS_WEBP_LIBRARY; and platform support
737        for the encoded format.
738
739        If SK_BUILD_FOR_MAC or SK_BUILD_FOR_IOS is defined, encodedImageFormat can
740        additionally be one of: SkEncodedImageFormat::kICO, SkEncodedImageFormat::kBMP,
741        SkEncodedImageFormat::kGIF.
742
743        quality is a platform and format specific metric trading off size and encoding
744        error. When used, quality equaling 100 encodes with the least error. quality may
745        be ignored by the encoder.
746
747        @param encodedImageFormat  one of: SkEncodedImageFormat::kJPEG, SkEncodedImageFormat::kPNG,
748                                   SkEncodedImageFormat::kWEBP
749        @param quality             encoder specific metric with 100 equaling best
750        @return                    encoded SkImage, or nullptr
751    */
752    sk_sp<SkData> encodeToData(SkEncodedImageFormat encodedImageFormat, int quality) const;
753
754    /** Encodes SkImage pixels, returning result as SkData. Returns existing encoded data
755        if present; otherwise, SkImage is encoded with SkEncodedImageFormat::kPNG. Skia
756        must be built with SK_HAS_PNG_LIBRARY to encode SkImage.
757
758        Returns nullptr if existing encoded data is missing or invalid, and
759        encoding fails.
760
761        @return  encoded SkImage, or nullptr
762    */
763    sk_sp<SkData> encodeToData() const;
764
765    /** Returns encoded SkImage pixels as SkData, if SkImage was created from supported
766        encoded stream format. Platform support for formats vary and may require building
767        with one or more of: SK_HAS_JPEG_LIBRARY, SK_HAS_PNG_LIBRARY, SK_HAS_WEBP_LIBRARY.
768
769        Returns nullptr if SkImage contents are not encoded.
770
771        @return  encoded SkImage, or nullptr
772    */
773    sk_sp<SkData> refEncodedData() const;
774
775    /** Appends SkImage description to string, including unique ID, width, height, and
776        whether the image is opaque.
777
778        @param string  storage for description; existing content is preserved
779        @return        string appended with SkImage description
780    */
781    const char* toString(SkString* string) const;
782
783    /** Returns subset of SkImage. subset must be fully contained by SkImage dimensions().
784        The implementation may share pixels, or may copy them.
785
786        Returns nullptr if subset is empty, or subset is not contained by bounds, or
787        pixels in SkImage could not be read or copied.
788
789        @param subset  bounds of returned SkImage
790        @return        partial or full SkImage, or nullptr
791    */
792    sk_sp<SkImage> makeSubset(const SkIRect& subset) const;
793
794    /** Returns SkImage backed by GPU texture associated with context. Returned SkImage is
795        compatible with SkSurface created with dstColorSpace. Returns original
796        SkImage if context and dstColorSpace match.
797
798        Returns nullptr if context is nullptr, or if SkImage was created with another
799        GrContext.
800
801        @param context        GPU context
802        @param dstColorSpace  range of colors of matching SkSurface on GPU
803        @return               created SkImage, or nullptr
804    */
805    sk_sp<SkImage> makeTextureImage(GrContext* context, SkColorSpace* dstColorSpace) const;
806
807    /** Returns raster image or lazy image. Copies SkImage backed by GPU texture into
808        CPU memory if needed. Returns original SkImage if decoded in raster bitmap,
809        or if encoded in a stream.
810
811        Returns nullptr if backed by GPU texture and copy fails.
812
813        @return  raster image, lazy image, or nullptr
814    */
815    sk_sp<SkImage> makeNonTextureImage() const;
816
817    /** Returns raster image. Copies SkImage backed by GPU texture into CPU memory,
818        or decodes SkImage from lazy image. Returns original SkImage if decoded in
819        raster bitmap.
820
821        Returns nullptr if copy, decode, or pixel read fails.
822
823        @return  raster image, or nullptr
824    */
825    sk_sp<SkImage> makeRasterImage() const;
826
827    /** Creates filtered SkImage. filter processes original SkImage, potentially changing
828        color, position, and size. subset is the bounds of original SkImage processed
829        by filter. clipBounds is the expected bounds of the filtered SkImage. outSubset
830        is required storage for the actual bounds of the filtered SkImage. offset is
831        required storage for translation of returned SkImage.
832
833        Returns nullptr if SkImage could not be created. If nullptr is returned, outSubset
834        and offset are undefined.
835
836        Useful for animation of SkImageFilter that varies size from frame to frame.
837        Returned SkImage is created larger than required by filter so that GPU texture
838        can be reused with different sized effects. outSubset describes the valid bounds
839        of GPU texture returned. offset translates the returned SkImage to keep subsequent
840        animation frames aligned with respect to each other.
841
842        @param filter      how SkImage is sampled when transformed
843        @param subset      bounds of SkImage processed by filter
844        @param clipBounds  expected bounds of filtered SkImage
845        @param outSubset   storage for returned SkImage bounds
846        @param offset      storage for returned SkImage translation
847        @return            filtered SkImage, or nullptr
848    */
849    sk_sp<SkImage> makeWithFilter(const SkImageFilter* filter, const SkIRect& subset,
850                                  const SkIRect& clipBounds, SkIRect* outSubset,
851                                  SkIPoint* offset) const;
852
853    typedef std::function<void(GrBackendTexture)> BackendTextureReleaseProc;
854
855    /** Creates a GrBackendTexture from the provided SkImage. Returns true and
856        stores result in backendTexture and backendTextureReleaseProc if
857        texture is created; otherwise, returns false and leaves
858        backendTexture and backendTextureReleaseProc unmodified.
859
860        Call backendTextureReleaseProc after deleting backendTexture.
861        backendTextureReleaseProc cleans up auxiliary data related to returned
862        backendTexture. The caller must delete returned backendTexture after use.
863
864        If SkImage is both texture backed and singly referenced, image is returned in
865        backendTexture without conversion or making a copy. SkImage is singly referenced
866        if its was transferred solely using std::move().
867
868        If SkImage is not texture backed, returns texture with SkImage contents.
869
870        @param context                    GPU context
871        @param image                      SkImage used for texture
872        @param backendTexture             storage for backend texture
873        @param backendTextureReleaseProc  storage for clean up function
874        @return                           true if backend texture was created
875    */
876    static bool MakeBackendTextureFromSkImage(GrContext* context,
877                                              sk_sp<SkImage> image,
878                                              GrBackendTexture* backendTexture,
879                                              BackendTextureReleaseProc* backendTextureReleaseProc);
880
881    enum LegacyBitmapMode {
882        kRO_LegacyBitmapMode, //!< Returned bitmap is read-only and immutable.
883    };
884
885    /** Creates raster SkBitmap with same pixels as SkImage. If legacyBitmapMode is
886        kRO_LegacyBitmapMode, returned bitmap is read-only and immutable.
887        Returns true if SkBitmap is stored in bitmap. Returns false and resets bitmap if
888        SkBitmap write did not succeed.
889
890        @param bitmap            storage for legacy SkBitmap
891        @param legacyBitmapMode  to be deprecated
892        @return                  true if SkBitmap was created
893    */
894    bool asLegacyBitmap(SkBitmap* bitmap, LegacyBitmapMode legacyBitmapMode = kRO_LegacyBitmapMode) const;
895
896    /** Returns true if SkImage is backed by an image-generator or other service that creates
897        and caches its pixels or texture on-demand.
898
899        @return  true if SkImage is created as needed
900    */
901    bool isLazyGenerated() const;
902
903    /** Creates SkImage in target SkColorSpace.
904        Returns nullptr if SkImage could not be created.
905
906        Returns original SkImage if it is in target SkColorSpace.
907        Otherwise, converts pixels from SkImage SkColorSpace to target SkColorSpace.
908        If SkImage colorSpace() returns nullptr, SkImage SkColorSpace is assumed to be sRGB.
909
910        SkTransferFunctionBehavior is to be deprecated.
911
912        Set premulBehavior to SkTransferFunctionBehavior::kRespect to convert SkImage
913        pixels to a linear space, before converting to destination SkColorType
914        and SkColorSpace.
915
916        Set premulBehavior to SkTransferFunctionBehavior::kIgnore to treat SkImage
917        pixels as linear, when converting to destination SkColorType
918        and SkColorSpace, ignoring pixel encoding.
919
920        @param target          SkColorSpace describing color range of returned SkImage
921        @param premulBehavior  one of: SkTransferFunctionBehavior::kRespect,
922                               SkTransferFunctionBehavior::kIgnore
923        @return                created SkImage in target SkColorSpace
924    */
925    sk_sp<SkImage> makeColorSpace(sk_sp<SkColorSpace> target,
926                                  SkTransferFunctionBehavior premulBehavior) const;
927
928private:
929    SkImage(int width, int height, uint32_t uniqueID);
930    friend class SkImage_Base;
931
932    const int       fWidth;
933    const int       fHeight;
934    const uint32_t  fUniqueID;
935
936    typedef SkRefCnt INHERITED;
937};
938
939#endif
940