SkImage Reference
===
---
class SkImage : public SkRefCnt {
public:
typedef void* ReleaseContext;
static sk_sp<SkImage> MakeRasterCopy(const SkPixmap& pixmap);
static sk_sp<SkImage> MakeRasterData(const SkImageInfo& info, sk_sp<SkData> pixels,
size_t rowBytes);
typedef void (*RasterReleaseProc)(const void* pixels, ReleaseContext);
static sk_sp<SkImage> MakeFromRaster(const SkPixmap& pixmap,
RasterReleaseProc rasterReleaseProc,
ReleaseContext releaseContext);
static sk_sp<SkImage> MakeFromBitmap(const SkBitmap& bitmap);
static sk_sp<SkImage> MakeFromGenerator(std::unique_ptr<SkImageGenerator> imageGenerator,
const SkIRect* subset = nullptr);
static sk_sp<SkImage> MakeFromEncoded(sk_sp<SkData> encoded, const SkIRect* subset = nullptr);
typedef void (*TextureReleaseProc)(ReleaseContext releaseContext);
static sk_sp<SkImage> MakeFromTexture(GrContext* context,
const GrBackendTexture& backendTexture,
GrSurfaceOrigin origin,
SkColorType colorType,
SkAlphaType alphaType,
sk_sp<SkColorSpace> colorSpace);
static sk_sp<SkImage> MakeFromTexture(GrContext* context,
const GrBackendTexture& backendTexture,
GrSurfaceOrigin origin,
SkColorType colorType,
SkAlphaType alphaType,
sk_sp<SkColorSpace> colorSpace,
TextureReleaseProc textureReleaseProc,
ReleaseContext releaseContext);
static sk_sp<SkImage> MakeCrossContextFromEncoded(GrContext* context, sk_sp<SkData> data,
bool buildMips, SkColorSpace* dstColorSpace,
bool limitToMaxTextureSize = false);
static sk_sp<SkImage> MakeCrossContextFromPixmap(GrContext* context, const SkPixmap& pixmap,
bool buildMips, SkColorSpace* dstColorSpace,
bool limitToMaxTextureSize = false);
static sk_sp<SkImage> MakeFromAdoptedTexture(GrContext* context,
const GrBackendTexture& backendTexture,
GrSurfaceOrigin surfaceOrigin,
SkColorType colorType,
SkAlphaType alphaType = kPremul_SkAlphaType,
sk_sp<SkColorSpace> colorSpace = nullptr);
static sk_sp<SkImage> MakeFromYUVATexturesCopy(GrContext* context,
SkYUVColorSpace yuvColorSpace,
const GrBackendTexture yuvaTextures[],
const SkYUVAIndex yuvaIndices[4],
SkISize imageSize,
GrSurfaceOrigin imageOrigin,
sk_sp<SkColorSpace> imageColorSpace = nullptr);
static sk_sp<SkImage> MakeFromYUVATexturesCopyWithExternalBackend(
GrContext* context,
SkYUVColorSpace yuvColorSpace,
const GrBackendTexture yuvaTextures[],
const SkYUVAIndex yuvaIndices[4],
SkISize imageSize,
GrSurfaceOrigin imageOrigin,
const GrBackendTexture& backendTexture,
sk_sp<SkColorSpace> imageColorSpace = nullptr);
static sk_sp<SkImage> MakeFromYUVTexturesCopy(GrContext* context, SkYUVColorSpace yuvColorSpace,
const GrBackendTexture yuvTextures[3],
GrSurfaceOrigin imageOrigin,
sk_sp<SkColorSpace> imageColorSpace = nullptr);
static sk_sp<SkImage> MakeFromYUVTexturesCopyWithExternalBackend(
GrContext* context, SkYUVColorSpace yuvColorSpace,
const GrBackendTexture yuvTextures[3], GrSurfaceOrigin imageOrigin,
const GrBackendTexture& backendTexture, sk_sp<SkColorSpace> imageColorSpace = nullptr);
static sk_sp<SkImage> MakeFromNV12TexturesCopy(GrContext* context,
SkYUVColorSpace yuvColorSpace,
const GrBackendTexture nv12Textures[2],
GrSurfaceOrigin imageOrigin,
sk_sp<SkColorSpace> imageColorSpace = nullptr);
static sk_sp<SkImage> MakeFromNV12TexturesCopyWithExternalBackend(
GrContext* context,
SkYUVColorSpace yuvColorSpace,
const GrBackendTexture nv12Textures[2],
GrSurfaceOrigin imageOrigin,
const GrBackendTexture& backendTexture,
sk_sp<SkColorSpace> imageColorSpace = nullptr);
enum class BitDepth {
kU8,
kF16,
};
static sk_sp<SkImage> MakeFromPicture(sk_sp<SkPicture> picture, const SkISize& dimensions,
const SkMatrix* matrix, const SkPaint* paint,
BitDepth bitDepth,
sk_sp<SkColorSpace> colorSpace);
static sk_sp<SkImage> MakeFromAHardwareBuffer(
AHardwareBuffer* hardwareBuffer,
SkAlphaType alphaType = kPremul_SkAlphaType,
sk_sp<SkColorSpace> colorSpace = nullptr,
GrSurfaceOrigin surfaceOrigin = kTopLeft_GrSurfaceOrigin);
int width() const;
int height() const;
SkISize dimensions() const;
SkIRect bounds() const;
uint32_t uniqueID() const;
SkAlphaType alphaType() const;
SkColorType colorType() const;
SkColorSpace* colorSpace() const;
sk_sp<SkColorSpace> refColorSpace() const;
bool isAlphaOnly() const;
bool isOpaque() const;
sk_sp<SkShader> makeShader(SkShader::TileMode tileMode1, SkShader::TileMode tileMode2,
const SkMatrix* localMatrix = nullptr) const;
sk_sp<SkShader> makeShader(const SkMatrix* localMatrix = nullptr) const;
bool peekPixels(SkPixmap* pixmap) const;
GrTexture* getTexture() const;
bool isTextureBacked() const;
bool isValid(GrContext* context) const;
GrBackendTexture getBackendTexture(bool flushPendingGrContextIO,
GrSurfaceOrigin* origin = nullptr) const;
enum CachingHint {
kAllow_CachingHint,
kDisallow_CachingHint,
};
bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes,
int srcX, int srcY, CachingHint cachingHint = kAllow_CachingHint) const;
bool readPixels(const SkPixmap& dst, int srcX, int srcY,
CachingHint cachingHint = kAllow_CachingHint) const;
bool scalePixels(const SkPixmap& dst, SkFilterQuality filterQuality,
CachingHint cachingHint = kAllow_CachingHint) const;
sk_sp<SkData> encodeToData(SkEncodedImageFormat encodedImageFormat, int quality) const;
sk_sp<SkData> encodeToData() const;
sk_sp<SkData> refEncodedData() const;
sk_sp<SkImage> makeSubset(const SkIRect& subset) const;
sk_sp<SkImage> makeTextureImage(GrContext* context, SkColorSpace* dstColorSpace,
GrMipMapped mipMapped = GrMipMapped::kNo) const;
sk_sp<SkImage> makeNonTextureImage() const;
sk_sp<SkImage> makeRasterImage() const;
sk_sp<SkImage> makeWithFilter(const SkImageFilter* filter, const SkIRect& subset,
const SkIRect& clipBounds, SkIRect* outSubset,
SkIPoint* offset) const;
typedef std::function BackendTextureReleaseProc;
static bool MakeBackendTextureFromSkImage(GrContext* context,
sk_sp<SkImage> image,
GrBackendTexture* backendTexture,
BackendTextureReleaseProc* backendTextureReleaseProc);
enum LegacyBitmapMode {
kRO_LegacyBitmapMode,
};
bool asLegacyBitmap(SkBitmap* bitmap,
LegacyBitmapMode legacyBitmapMode = kRO_LegacyBitmapMode) const;
bool isLazyGenerated() const;
sk_sp<SkImage> makeColorSpace(sk_sp<SkColorSpace> target) const;
};
Image describes a two dimensional array of pixels to draw. The pixels may be
decoded in a Raster Bitmap, encoded in a Picture or compressed data stream,
or located in GPU memory as a GPU Texture.
Image cannot be modified after it is created. Image may allocate additional
storage as needed; for instance, an encoded Image may decode when drawn.
Image width and height are greater than zero. Creating an Image with zero width
or height returns Image equal to nullptr.
Image may be created from Bitmap, Pixmap, Surface, Picture, encoded streams,
GPU Texture, YUV ColorSpace data, or hardware buffer. Encoded streams supported
include BMP, GIF, HEIF, ICO, JPEG, PNG, WBMP, WebP. Supported encoding details
vary with platform.
Raster Image pixels are decoded in a Raster Bitmap. These pixels may be read
directly and in most cases written to, although edited pixels may not be drawn
if Image has been copied internally.
Texture Image are located on GPU and pixels are not accessible. Texture Image
are allocated optimally for best performance. Raster Image may
be drawn to GPU Surface, but pixels are uploaded from CPU to GPU downgrading
performance.
Lazy Image defer allocating buffer for Image pixels and decoding stream until
Image is drawn. Lazy Image caches result if possible to speed up repeated
drawing.
---
static sk sp<SkImage> MakeRasterCopy(const SkPixmap& pixmap)
Creates Image from Pixmap and copy of pixels. Since pixels are copied, Pixmap
pixels may be modified or deleted without affecting Image.
Image is returned if Pixmap is valid. Valid Pixmap parameters include:
dimensions are greater than zero;
each dimension fits in 29 bits;
Color Type and Alpha Type are valid, and Color Type is not kUnknown_SkColorType;
row bytes are large enough to hold one row of pixels;
pixel address is not nullptr.
### Parameters
### Return Value
copy of Pixmap pixels, or nullptr
### Example
Draw a five by five bitmap, and draw a copy in an
Image. Editing the
pixmap
alters the bitmap draw, but does not alter the
Image draw since the
Image
contains a copy of the pixels.
static sk sp<SkImage> MakeRasterData(const SkImageInfo& info, sk sp<SkData> pixels, size_t rowBytes)
Creates Image from Image Info, sharing pixels.
Image is returned if Image Info is valid. Valid Image Info parameters include:
dimensions are greater than zero;
each dimension fits in 29 bits;
Color Type and Alpha Type are valid, and Color Type is not kUnknown_SkColorType;
rowBytes are large enough to hold one row of pixels;
pixels is not nullptr, and contains enough data for Image.
### Parameters
### Return Value
Image sharing pixels, or nullptr
### Example
### See Also
MakeRasterCopy MakeFromGenerator
---
typedef void* ReleaseContext;
Caller data passed to RasterReleaseProc; may be nullptr.
### See Also
MakeFromRaster RasterReleaseProc
---
typedef void (*RasterReleaseProc)(const void* pixels, ReleaseContext);
Function called when Image no longer shares pixels. ReleaseContext is
provided by caller when Image is created, and may be nullptr.
### See Also
ReleaseContext MakeFromRaster
---
static sk sp<SkImage> MakeFromRaster(const SkPixmap& pixmap, RasterReleaseProc rasterReleaseProc,
ReleaseContext releaseContext)
Creates Image from pixmap, sharing Pixmap pixels. Pixels must remain valid and
unchanged until rasterReleaseProc is called. rasterReleaseProc is passed
releaseContext when Image is deleted or no longer refers to pixmap pixels.
Pass nullptr for rasterReleaseProc to share Pixmap without requiring a callback
when Image is released. Pass nullptr for releaseContext if rasterReleaseProc
does not require state.
Image is returned if pixmap is valid. Valid Pixmap parameters include:
dimensions are greater than zero;
each dimension fits in 29 bits;
Color Type and Alpha Type are valid, and Color Type is not kUnknown_SkColorType;
row bytes are large enough to hold one row of pixels;
pixel address is not nullptr.
### Parameters
### Return Value
Image sharing pixmap
### Example
#### Example Output
~~~~
before reset: 0
after reset: 1
~~~~
### See Also
MakeRasterCopy MakeRasterData MakeFromGenerator RasterReleaseProc ReleaseContext
---
static sk sp<SkImage> MakeFromBitmap(const SkBitmap& bitmap)
Creates Image from bitmap, sharing or copying bitmap pixels. If the bitmap
is marked immutable, and its pixel memory is shareable, it may be shared
instead of copied.
Image is returned if bitmap is valid. Valid Bitmap parameters include:
dimensions are greater than zero;
each dimension fits in 29 bits;
Color Type and Alpha Type are valid, and Color Type is not kUnknown_SkColorType;
row bytes are large enough to hold one row of pixels;
pixel address is not nullptr.
### Parameters
### Return Value
created Image, or nullptr
### Example
The first
Bitmap is shared; writing to the pixel memory changes the first
Image.
The second
Bitmap is marked immutable, and is copied; writing to the pixel
memory does not alter the second
Image.
static sk sp<SkImage> MakeFromGenerator(std::unique_ptr<SkImageGenerator> imageGenerator,
const SkIRect* subset = nullptr)
Creates Image from data returned by imageGenerator. Generated data is owned by Image and may not
be shared or accessed.
subset allows selecting a portion of the full image. Pass nullptr to select the entire image;
otherwise, subset must be contained by image bounds.
Image is returned if generator data is valid. Valid data parameters vary by type of data
and platform.
imageGenerator may wrap Picture data, codec data, or custom data.
### Parameters
### Return Value
created Image, or nullptr
### Example
The generator returning
Picture cannot be shared; std::move transfers ownership to generated
Image.
static sk sp<SkImage> MakeFromEncoded(sk sp<SkData> encoded, const SkIRect* subset = nullptr)
Creates Image from encoded data.
subset allows selecting a portion of the full image. Pass nullptr to select the entire image;
otherwise, subset must be contained by image bounds.
Image is returned if format of the encoded data is recognized and supported.
Recognized formats vary by platform.
### Parameters
### Return Value
created Image, or nullptr
### Example
### See Also
MakeFromGenerator
---
typedef void (*TextureReleaseProc)(ReleaseContext releaseContext);
User function called when supplied texture may be deleted.
### See Also
MakeFromTexture[2]
---
static sk sp<SkImage> MakeFromTexture(GrContext* context, const GrBackendTexture& backendTexture,
GrSurfaceOrigin origin, SkColorType colorType,
SkAlphaType alphaType, sk sp<SkColorSpace> colorSpace)
Creates Image from GPU Texture associated with context. Caller is responsible for
managing the lifetime of GPU Texture.
Image is returned if format of backendTexture is recognized and supported.
Recognized formats vary by GPU back-end.
### Parameters
context |
GPU Context |
backendTexture |
texture residing on GPU |
origin |
one of: kBottomLeft GrSurfaceOrigin, kTopLeft GrSurfaceOrigin |
colorType |
one of: kUnknown_SkColorType, kAlpha_8_SkColorType, kRGB_565_SkColorType,
kARGB_4444_SkColorType, kRGBA_8888_SkColorType, kRGB_888x_SkColorType,
kBGRA_8888_SkColorType, kRGBA_1010102_SkColorType, kRGB_101010x_SkColorType,
kGray_8_SkColorType, kRGBA_F16_SkColorType |
alphaType |
one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType, kPremul_SkAlphaType,
kUnpremul_SkAlphaType |
colorSpace |
range of colors; may be nullptr |
### Return Value
created Image, or nullptr
### Example
A back-end texture has been created and uploaded to the GPU outside of this example.
static sk sp<SkImage> MakeFromTexture(GrContext* context, const GrBackendTexture& backendTexture,
GrSurfaceOrigin origin, SkColorType colorType,
SkAlphaType alphaType, sk sp<SkColorSpace> colorSpace,
TextureReleaseProc textureReleaseProc,
ReleaseContext releaseContext)
Creates Image from GPU Texture associated with context. GPU Texture must stay
valid and unchanged until textureReleaseProc is called. textureReleaseProc is
passed releaseContext when Image is deleted or no longer refers to texture.
Image is returned if format of backendTexture is recognized and supported.
Recognized formats vary by GPU back-end.
### Parameters
context |
GPU Context |
backendTexture |
texture residing on GPU |
origin |
one of: kBottomLeft GrSurfaceOrigin, kTopLeft GrSurfaceOrigin |
colorType |
one of: kUnknown_SkColorType, kAlpha_8_SkColorType, kRGB_565_SkColorType,
kARGB_4444_SkColorType, kRGBA_8888_SkColorType, kRGB_888x_SkColorType,
kBGRA_8888_SkColorType, kRGBA_1010102_SkColorType, kRGB_101010x_SkColorType,
kGray_8_SkColorType, kRGBA_F16_SkColorType |
alphaType |
one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType, kPremul_SkAlphaType,
kUnpremul_SkAlphaType |
colorSpace |
range of colors; may be nullptr |
textureReleaseProc |
function called when texture can be released |
releaseContext |
state passed to textureReleaseProc |
### Return Value
created Image, or nullptr
### Example
### See Also
MakeFromAdoptedTexture SkSurface::MakeFromBackendTexture
---
static sk sp<SkImage> MakeCrossContextFromEncoded(GrContext* context, sk sp<SkData> data,
bool buildMips, SkColorSpace* dstColorSpace,
bool limitToMaxTextureSize = false)
Creates Image from encoded data. Image is uploaded to GPU back-end using context.
Created Image is available to other GPU contexts, and is available across thread
boundaries. All contexts must be in the same GPU Share Group, or otherwise
share resources.
When Image is no longer referenced, context releases texture memory
asynchronously.
Texture decoded from data is uploaded to match Surface created with
dstColorSpace. Color Space of Image is determined by encoded data.
Image is returned if format of data is recognized and supported, and if context
supports moving resources. Recognized formats vary by platform and GPU back-end.
Image is returned using MakeFromEncoded if context is nullptr or does not support
moving resources between contexts.
### Parameters
### Return Value
created Image, or nullptr
### Example
### See Also
MakeCrossContextFromPixmap
---
static sk sp<SkImage> MakeCrossContextFromPixmap(GrContext* context, const SkPixmap& pixmap,
bool buildMips, SkColorSpace* dstColorSpace,
bool limitToMaxTextureSize = false)
Creates Image from pixmap. Image is uploaded to GPU back-end using context.
Created Image is available to other GPU contexts, and is available across thread
boundaries. All contexts must be in the same GPU Share Group, or otherwise
share resources.
When Image is no longer referenced, context releases texture memory
asynchronously.
Texture created from pixmap is uploaded to match Surface created with
dstColorSpace. Color Space of Image is determined by pixmap.colorSpace().
Image is returned referring to GPU back-end if context is not nullptr,
format of data is recognized and supported, and if context supports moving
resources between contexts. Otherwise, pixmap pixel data is copied and Image
as returned in raster format if possible; nullptr may be returned.
Recognized GPU formats vary by platform and GPU back-end.
### Parameters
### Return Value
created Image, or nullptr
### Example
### See Also
MakeCrossContextFromEncoded
---
static sk sp<SkImage> MakeFromAdoptedTexture(GrContext* context,
const GrBackendTexture& backendTexture,
GrSurfaceOrigin surfaceOrigin, SkColorType colorType,
SkAlphaType alphaType = kPremul_SkAlphaType,
sk sp<SkColorSpace> colorSpace = nullptr)
Creates Image from backendTexture associated with context. backendTexture and
returned Image are managed internally, and are released when no longer needed.
Image is returned if format of backendTexture is recognized and supported.
Recognized formats vary by GPU back-end.
### Parameters
context |
GPU Context |
backendTexture |
texture residing on GPU |
surfaceOrigin |
one of: kBottomLeft GrSurfaceOrigin, kTopLeft GrSurfaceOrigin |
colorType |
one of: kUnknown_SkColorType, kAlpha_8_SkColorType, kRGB_565_SkColorType,
kARGB_4444_SkColorType, kRGBA_8888_SkColorType, kRGB_888x_SkColorType,
kBGRA_8888_SkColorType, kRGBA_1010102_SkColorType, kRGB_101010x_SkColorType,
kGray_8_SkColorType, kRGBA_F16_SkColorType |
alphaType |
one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType, kPremul_SkAlphaType,
kUnpremul_SkAlphaType |
colorSpace |
range of colors; may be nullptr |
### Return Value
created Image, or nullptr
### Example
### See Also
MakeFromTexture[2] MakeFromYUVTexturesCopy
---
static sk sp<SkImage> MakeFromYUVATexturesCopy(GrContext* context, SkYUVColorSpace yuvColorSpace,
const GrBackendTexture yuvaTextures[],
const SkYUVAIndex yuvaIndices[4], SkISize imageSize,
GrSurfaceOrigin imageOrigin,
sk sp<SkColorSpace> imageColorSpace = nullptr)
Creates an SkImage by flattening the specified YUVA planes into a single,
interleaved RGBA image.
yuvaTextures points to array of up to four YUVA textures which reside on GPU.
YUVA textures contain YUVA planes which may be interleaved.
### Parameters
### Return Value
created SkImage, or nullptr
### See Also
MakeFromYUVATexturesCopyWithExternalBackend
---
static sk sp<SkImage> MakeFromYUVATexturesCopyWithExternalBackend(
GrContext* context,
SkYUVColorSpace yuvColorSpace, const GrBackendTexture yuvaTextures[],
const SkYUVAIndex yuvaIndices[4], SkISize imageSize,
GrSurfaceOrigin imageOrigin, const GrBackendTexture& backendTexture,
sk sp<SkColorSpace> imageColorSpace = nullptr)
Creates an SkImage by flattening the specified YUVA planes into a single,
interleaved RGBA image. backendTexture is used to store the result of flattening.
yuvaTextures points to array of up to four YUVA textures which reside on GPU.
YUVA textures contain YUVA planes which may be interleaved.
### Parameters
### Return Value
created SkImage, or nullptr
### See Also
MakeFromYUVATexturesCopy
---
static sk sp<SkImage> MakeFromYUVTexturesCopy(GrContext* context, SkYUVColorSpace yuvColorSpace,
const GrBackendTexture yuvTextures[3],
GrSurfaceOrigin imageOrigin,
sk sp<SkColorSpace> imageColorSpace = nullptr)
Creates Image from copy of yuvTextures, an array of textures on GPU.
yuvTextures contain pixels for YUV planes of Image. Returned Image has the dimensions
yuvTextures[0]. yuvColorSpace describes how YUV colors convert to RGB colors.
### Parameters
### Return Value
created Image, or nullptr
### See Also
MakeFromYUVTexturesCopyWithExternalBackend MakeFromNV12TexturesCopy MakeFromYUVATexturesCopy
---
static sk sp<SkImage> MakeFromYUVTexturesCopyWithExternalBackend(
GrContext* context,
SkYUVColorSpace yuvColorSpace, const GrBackendTexture yuvTextures[3],
GrSurfaceOrigin imageOrigin, const GrBackendTexture& backendTexture,
sk sp<SkColorSpace> imageColorSpace = nullptr) ;
Creates Image from copy of yuvTextures, an array of textures on GPU.
yuvTextures contain pixels for YUV planes of Image. Returned Image has the dimensions
yuvTextures[0] and stores pixels in backendTexture. yuvColorSpace describes how YUV colors
convert to RGB colors.
### Parameters
### Return Value
created SkImage, or nullptr
### See Also
MakeFromYUVTexturesCopy MakeFromNV12TexturesCopy MakeFromYUVATexturesCopyWithExternalBackend
---
static sk sp<SkImage> MakeFromNV12TexturesCopy(GrContext* context, SkYUVColorSpace yuvColorSpace,
const GrBackendTexture nv12Textures[2],
GrSurfaceOrigin imageOrigin,
sk sp<SkColorSpace> imageColorSpace = nullptr)
Creates Image from copy of nv12Textures, an array of textures on GPU.
nv12Textures[0] contains pixels for YUV Component Y plane.
nv12Textures[1] contains pixels for YUV Component U plane,
followed by pixels for YUV Component V plane.
Returned Image has the dimensions nv12Textures[2].
yuvColorSpace describes how YUV colors convert to RGB colors.
### Parameters
### Return Value
created Image, or nullptr
### See Also
MakeFromNV12TexturesCopyWithExternalBackend MakeFromYUVTexturesCopy MakeFromYUVATexturesCopy
---
static sk sp<SkImage> MakeFromNV12TexturesCopyWithExternalBackend(
GrContext* context,
SkYUVColorSpace yuvColorSpace, const GrBackendTexture nv12Textures[2],
GrSurfaceOrigin imageOrigin, const GrBackendTexture& backendTexture,
sk sp<SkColorSpace> imageColorSpace = nullptr) ;
Creates Image from copy of nv12Textures, an array of textures on GPU.
nv12Textures[0] contains pixels for YUV Component Y plane.
nv12Textures[1] contains pixels for YUV Component U plane,
followed by pixels for YUV Component V plane.
Returned Image has the dimensions nv12Textures[2] and stores pixels in backendTexture.
yuvColorSpace describes how YUV colors convert to RGB colors.
### Parameters
### Return Value
created Image, or nullptr
### See Also
MakeFromNV12TexturesCopy MakeFromYUVTexturesCopy MakeFromYUVATexturesCopyWithExternalBackend
---
enum class BitDepth {
kU8,
kF16,
};
### Constants
### See Also
MakeFromPicture
---
static sk sp<SkImage> MakeFromPicture(sk sp<SkPicture> picture, const SkISize& dimensions,
const SkMatrix* matrix, const SkPaint* paint,
BitDepth bitDepth, sk sp<SkColorSpace> colorSpace)
Creates Image from picture. Returned Image width and height are set by dimensions.
Image draws picture with matrix and paint, set to bitDepth and colorSpace.
If matrix is nullptr, draws with identity Matrix. If paint is nullptr, draws
with default Paint. colorSpace may be nullptr.
### Parameters
picture |
stream of drawing commands |
dimensions |
width and height |
matrix |
Matrix to rotate, scale, translate, and so on; may be nullptr |
paint |
Paint to apply transparency, filtering, and so on; may be nullptr |
bitDepth |
8-bit integer or 16-bit float: per component |
colorSpace |
range of colors; may be nullptr |
### Return Value
created Image, or nullptr
### Example
### See Also
SkCanvas::drawPicture[2][3][4]
---
static sk sp<SkImage> MakeFromAHardwareBuffer(
AHardwareBuffer* hardwareBuffer,
SkAlphaType alphaType = kPremul_SkAlphaType,
sk sp<SkColorSpace> colorSpace = nullptr,
GrSurfaceOrigin surfaceOrigin = kTopLeft GrSurfaceOrigin)
Creates Image from Android hardware buffer.
Returned Image takes a reference on the buffer.
Only available on Android, when __ANDROID_API__ is defined to be 26 or greater.
### Parameters
### Return Value
created Image, or nullptr
### See Also
MakeFromRaster
---
int width() const
Returns pixel count in each row.
### Return Value
pixel width in Image
### Example
### See Also
dimensions() height()
---
int height() const
Returns pixel row count.
### Return Value
pixel height in Image
### Example
### See Also
dimensions() width()
---
SkISize dimensions() const
Returns ISize { width(), height() }.
### Return Value
integral size of width() and height()
### Example
#### Example Output
~~~~
dimensionsAsBounds == bounds
~~~~
### See Also
height() width() bounds()
---
SkIRect bounds() const
Returns IRect { 0, 0, width(), height() }.
### Return Value
integral rectangle from origin to width() and height()
### Example
### See Also
dimensions()
---
uint32_t uniqueID() const
Returns value unique to image. Image contents cannot change after Image is
created. Any operation to create a new Image will receive generate a new
unique number.
### Return Value
unique identifier
### Example
### See Also
isLazyGenerated
---
SkAlphaType alphaType() const
Returns Alpha Type, one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType, kPremul_SkAlphaType,
kUnpremul_SkAlphaType.
Alpha Type returned was a parameter to an Image constructor,
or was parsed from encoded data.
### Return Value
Alpha Type in Image
### Example
### See Also
SkImageInfo::alphaType
---
SkColorType colorType() const
Returns Color Type if known; otherwise, returns kUnknown_SkColorType.
### Return Value
Color Type of Image
### Example
### See Also
SkImageInfo::colorType
---
SkColorSpace* colorSpace() const
Returns Color Space, the range of colors, associated with Image. The
reference count of Color Space is unchanged. The returned Color Space is
immutable.
Color Space returned was passed to an Image constructor,
or was parsed from encoded data. Color Space returned may be ignored when Image
is drawn, depending on the capabilities of the Surface receiving the drawing.
### Return Value
Color Space in Image, or nullptr
### Example
### See Also
refColorSpace makeColorSpace
---
sk sp<SkColorSpace> refColorSpace() const
Returns a smart pointer to Color Space, the range of colors, associated with
Image. The smart pointer tracks the number of objects sharing this
SkColorSpace reference so the memory is released when the owners destruct.
The returned SkColorSpace is immutable.
Color Space returned was passed to an Image constructor,
or was parsed from encoded data. Color Space returned may be ignored when Image
is drawn, depending on the capabilities of the Surface receiving the drawing.
### Return Value
Color Space in Image, or nullptr, wrapped in a smart pointer
### Example
### See Also
colorSpace makeColorSpace
---
bool isAlphaOnly() const
Returns true if Image pixels represent transparency only. If true, each pixel
is packed in 8 bits as defined by kAlpha_8_SkColorType.
### Return Value
true if pixels represent a transparency mask
### Example
#### Example Output
~~~~
alphaOnly = true
~~~~
### See Also
alphaType isOpaque
---
bool isOpaque() const
Returns true if pixels ignore their Alpha value and are treated as fully opaque.
### Return Value
true if Alpha Type is kOpaque_SkAlphaType
### Example
#### Example Output
~~~~
isOpaque = false
isOpaque = true
~~~~
### See Also
alphaType isAlphaOnly
---
sk sp<SkShader> makeShader(SkShader::TileMode tileMode1, SkShader::TileMode tileMode2,
const SkMatrix* localMatrix = nullptr) const
Creates Shader from Image. Shader dimensions are taken from Image. Shader uses
SkShader::TileMode rules to fill drawn area outside Image. localMatrix permits
transforming Image before Canvas Matrix is applied.
### Parameters
### Return Value
Shader containing Image
### Example
### See Also
scalePixels
---
sk sp<SkShader> makeShader(const SkMatrix* localMatrix = nullptr) const
Creates Shader from Image. Shader dimensions are taken from Image. Shader uses
SkShader::kClamp TileMode to fill drawn area outside Image. localMatrix permits
transforming Image before Canvas Matrix is applied.
### Parameters
### Return Value
Shader containing Image
### Example
### See Also
scalePixels
---
bool peekPixels(SkPixmap* pixmap) const
Copies Image pixel address, row bytes, and Image Info to pixmap, if address
is available, and returns true. If pixel address is not available, return
false and leave pixmap unchanged.
### Parameters
pixmap |
storage for pixel state if pixels are readable; otherwise, ignored |
### Return Value
true if Image has direct access to pixels
### Example
#### Example Output
~~~~
------------
--xx----x---
-x--x--x----
-x--x--x----
-x--x-x-----
--xx-xx-xx--
-----x-x--x-
----x--x--x-
----x--x--x-
---x----xx--
------------
~~~~
### See Also
readPixels[2]
---
GrTexture* getTexture() const
Deprecated.
---
bool isTextureBacked() const
Returns true the contents of Image was created on or uploaded to GPU memory,
and is available as a GPU Texture.
### Return Value
true if Image is a GPU Texture
### Example
### See Also
MakeFromTexture[2] isValid
---
bool isValid(GrContext* context) const
Returns true if Image can be drawn on either Raster Surface or GPU Surface.
If context is nullptr, tests if Image draws on Raster Surface;
otherwise, tests if Image draws on GPU Surface associated with context.
Image backed by GPU Texture may become invalid if associated GrContext is
invalid. Lazy Image may be invalid and may not draw to Raster Surface or
GPU Surface or both.
### Parameters
### Return Value
true if Image can be drawn
### Example
### See Also
isTextureBacked isLazyGenerated
---
GrBackendTexture getBackendTexture(bool flushPendingGrContextIO, GrSurfaceOrigin* origin = nullptr) const
Retrieves the back-end texture. If Image has no back-end texture, an invalid
object is returned. Call GrBackendTexture::isValid to determine if the result
is valid.
If flushPendingGrContextIO is true, completes deferred I/O operations.
If origin in not nullptr, copies location of content drawn into Image.
### Parameters
### Return Value
back-end API texture handle; invalid on failure
### Example
### See Also
MakeFromTexture[2] isTextureBacked
---
enum CachingHint {
kAllow_CachingHint,
kDisallow_CachingHint,
};
CachingHint selects whether Skia may internally cache Bitmaps generated by
decoding Image, or by copying Image from GPU to CPU. The default behavior
allows caching Bitmaps.
Choose kDisallow CachingHint if Image pixels are to be used only once, or
if Image pixels reside in a cache outside of Skia, or to reduce memory pressure.
Choosing kAllow CachingHint does not ensure that pixels will be cached.
Image pixels may not be cached if memory requirements are too large or
pixels are not accessible.
### Constants
### See Also
readPixels[2] scalePixels
---
bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes, int srcX, int srcY,
CachingHint cachingHint = kAllow CachingHint) const
Copies Rect of pixels from Image to dstPixels. Copy starts at offset (srcX, srcY),
and does not exceed Image (width(), height()).
dstInfo specifies width, height, Color Type, Alpha Type, and Color Space of
destination. dstRowBytes specifics the gap from one destination row to the next.
Returns true if pixels are copied. Returns false if:
Pixels are copied only if pixel conversion is possible. If Image Color Type is
kGray_8_SkColorType, or kAlpha_8_SkColorType; dstInfo.colorType must match.
If Image Color Type is kGray_8_SkColorType, dstInfo.colorSpace must match.
If Image Alpha Type is kOpaque_SkAlphaType, dstInfo.alphaType must
match. If Image Color Space is nullptr, dstInfo.colorSpace must match. Returns
false if pixel conversion is not possible.
srcX and srcY may be negative to copy only top or left of source. Returns
false if width() or height() is zero or negative.
Returns false if abs(srcX) >= Image width(\), or if abs(srcY) >= Image height(\).
If cachingHint is kAllow CachingHint, pixels may be retained locally.
If cachingHint is kDisallow CachingHint, pixels are not added to the local cache.
### Parameters
### Return Value
true if pixels are copied to dstPixels
### Example
### See Also
scalePixels SkBitmap::readPixels[2][3] SkPixmap::readPixels[2][3][4] SkCanvas::readPixels[2][3] SkSurface::readPixels[2][3]
---
bool readPixels(const SkPixmap& dst, int srcX, int srcY, CachingHint cachingHint = kAllow CachingHint) const
Copies a Rect of pixels from Image to dst. Copy starts at (srcX, srcY), and
does not exceed Image (width(), height()).
dst specifies width, height, Color Type, Alpha Type, Color Space, pixel storage,
and row bytes of destination. dst.rowBytes specifics the gap from one destination
row to the next. Returns true if pixels are copied. Returns false if:
Pixels are copied only if pixel conversion is possible. If Image Color Type is
kGray_8_SkColorType, or kAlpha_8_SkColorType; dst.colorType must match.
If Image Color Type is kGray_8_SkColorType, dst.colorSpace must match.
If Image Alpha Type is kOpaque_SkAlphaType, dst.alphaType must
match. If Image Color Space is nullptr, dst.colorSpace must match. Returns
false if pixel conversion is not possible.
srcX and srcY may be negative to copy only top or left of source. Returns
false if width() or height() is zero or negative.
Returns false if abs(srcX) >= Image width(\), or if abs(srcY) >= Image height(\).
If cachingHint is kAllow CachingHint, pixels may be retained locally.
If cachingHint is kDisallow CachingHint, pixels are not added to the local cache.
### Parameters
### Return Value
true if pixels are copied to dst
### Example
### See Also
scalePixels SkBitmap::readPixels[2][3] SkPixmap::readPixels[2][3][4] SkCanvas::readPixels[2][3] SkSurface::readPixels[2][3]
---
bool scalePixels(const SkPixmap& dst, SkFilterQuality filterQuality,
CachingHint cachingHint = kAllow CachingHint) const
Copies Image to dst, scaling pixels to fit dst.width() and dst.height(), and
converting pixels to match dst.colorType and dst.alphaType. Returns true if
pixels are copied. Returns false if dst.addr() is nullptr, or dst.rowBytes is
less than dst SkImageInfo::minRowBytes.
Pixels are copied only if pixel conversion is possible. If Image Color Type is
kGray_8_SkColorType, or kAlpha_8_SkColorType; dst.colorType must match.
If Image Color Type is kGray_8_SkColorType, dst.colorSpace must match.
If Image Alpha Type is kOpaque_SkAlphaType, dst.alphaType must
match. If Image Color Space is nullptr, dst.colorSpace must match. Returns
false if pixel conversion is not possible.
Scales the image, with filterQuality, to match dst.width() and dst.height().
filterQuality kNone_SkFilterQuality is fastest, typically implemented with
Filter Quality Nearest Neighbor. kLow_SkFilterQuality is typically implemented with
Filter Quality Bilerp. kMedium_SkFilterQuality is typically implemented with
Filter Quality Bilerp, and Filter Quality MipMap when size is reduced.
kHigh_SkFilterQuality is slowest, typically implemented with Filter Quality BiCubic.
If cachingHint is kAllow CachingHint, pixels may be retained locally.
If cachingHint is kDisallow CachingHint, pixels are not added to the local cache.
### Parameters
### Return Value
true if pixels are scaled to fit dst
### Example
### See Also
SkCanvas::drawImage[2] readPixels[2] SkPixmap::scalePixels
---
sk sp<SkData> encodeToData(SkEncodedImageFormat encodedImageFormat, int quality) const
Encodes Image pixels, returning result as SkData.
Returns nullptr if encoding fails, or if encodedImageFormat is not supported.
Image encoding in a format requires both building with one or more of:
SK_HAS_JPEG_LIBRARY, SK_HAS_PNG_LIBRARY, SK_HAS_WEBP_LIBRARY; and platform support
for the encoded format.
If SK_BUILD_FOR_MAC or SK_BUILD_FOR_IOS is defined, encodedImageFormat can
additionally be one of: SkEncodedImageFormat::kICO, SkEncodedImageFormat::kBMP,
SkEncodedImageFormat::kGIF.
quality is a platform and format specific metric trading off size and encoding
error. When used, quality equaling 100 encodes with the least error. quality may
be ignored by the encoder.
### Parameters
### Return Value
encoded Image, or nullptr
### Example
### See Also
refEncodedData MakeFromEncoded
---
sk sp<SkData> encodeToData() const
Encodes Image pixels, returning result as SkData. Returns existing encoded data
if present; otherwise, Image is encoded with SkEncodedImageFormat::kPNG. Skia
must be built with SK_HAS_PNG_LIBRARY to encode Image.
Returns nullptr if existing encoded data is missing or invalid, and
encoding fails.
### Return Value
encoded Image, or nullptr
### Example
### See Also
refEncodedData MakeFromEncoded
---
sk sp<SkData> refEncodedData() const
Returns encoded Image pixels as SkData, if Image was created from supported
encoded stream format. Platform support for formats vary and may require building
with one or more of: SK_HAS_JPEG_LIBRARY, SK_HAS_PNG_LIBRARY, SK_HAS_WEBP_LIBRARY.
Returns nullptr if Image contents are not encoded.
### Return Value
encoded Image, or nullptr
### Example
### See Also
encodeToData[2] MakeFromEncoded
---
sk sp<SkImage> makeSubset(const SkIRect& subset) const
Returns subset of Image. subset must be fully contained by Image dimensions().
The implementation may share pixels, or may copy them.
Returns nullptr if subset is empty, or subset is not contained by bounds, or
pixels in Image could not be read or copied.
### Parameters
### Return Value
partial or full Image, or nullptr
### Example
### See Also
MakeFromEncoded
---
sk sp<SkImage> makeTextureImage(GrContext* context, SkColorSpace* dstColorSpace,
GrMipMapped mipMapped = GrMipMapped::kNo) const
Returns Image backed by GPU Texture associated with context. Returned Image is
compatible with Surface created with dstColorSpace. The returned Image respects
mipMapped setting; if mipMapped equals GrMipMapped::kYes, the backing texture
allocates Mip Map levels. Returns original Image if context
and dstColorSpace match and mipMapped is compatible with backing GPU Texture.
Returns nullptr if context is nullptr, or if Image was created with another
GrContext.
### Parameters
### Return Value
created Image, or nullptr
### Example
### See Also
MakeFromTexture[2]
---
sk sp<SkImage> makeNonTextureImage() const
Returns Raster Image or Lazy Image. Copies Image backed by GPU Texture into
CPU memory if needed. Returns original Image if decoded in Raster Bitmap,
or if encoded in a stream.
Returns nullptr if backed by GPU Texture and copy fails.
### Return Value
Raster Image, Lazy Image, or nullptr
### Example
### See Also
makeTextureImage makeRasterImage MakeBackendTextureFromSkImage
---
sk sp<SkImage> makeRasterImage() const
Returns Raster Image. Copies Image backed by GPU Texture into CPU memory,
or decodes Image from Lazy Image. Returns original Image if decoded in
Raster Bitmap.
Returns nullptr if copy, decode, or pixel read fails.
### Return Value
Raster Image, or nullptr
### Example
### See Also
isTextureBacked isLazyGenerated MakeFromRaster
---
sk sp<SkImage> makeWithFilter(const SkImageFilter* filter, const SkIRect& subset,
const SkIRect& clipBounds, SkIRect* outSubset, SkIPoint* offset) const
Creates filtered Image. filter processes original Image, potentially changing
color, position, and size. subset is the bounds of original Image processed
by filter. clipBounds is the expected bounds of the filtered Image. outSubset
is required storage for the actual bounds of the filtered Image. offset is
required storage for translation of returned Image.
Returns nullptr if Image could not be created. If nullptr is returned, outSubset
and offset are undefined.
Useful for animation of SkImageFilter that varies size from frame to frame.
Returned Image is created larger than required by filter so that GPU Texture
can be reused with different sized effects. outSubset describes the valid bounds
of GPU Texture returned. offset translates the returned Image to keep subsequent
animation frames aligned with respect to each other.
### Parameters
### Return Value
filtered Image, or nullptr
### Example
In each frame of the animation, filtered
Image is drawn in a different location.
By translating canvas by returned
offset,
Image appears stationary.
typedef std::function BackendTextureReleaseProc;
Defines a callback function, taking one parameter of type GrBackendTexture with
no return value. Function is called when back-end texture is to be released.
---
static bool MakeBackendTextureFromSkImage(GrContext* context, sk sp<SkImage> image,
GrBackendTexture* backendTexture,
BackendTextureReleaseProc* backendTextureReleaseProc)
Creates a GrBackendTexture from the provided SkImage. Returns true and
stores result in backendTexture and backendTextureReleaseProc if
texture is created; otherwise, returns false and leaves
backendTexture and backendTextureReleaseProc unmodified.
Call backendTextureReleaseProc after deleting backendTexture.
backendTextureReleaseProc cleans up auxiliary data related to returned
backendTexture. The caller must delete returned backendTexture after use.
If Image is both texture backed and singly referenced, image is returned in
backendTexture without conversion or making a copy. Image is singly referenced
if its was transferred solely using std::move().
If Image is not texture backed, returns texture with Image contents.
### Parameters
### Return Value
true if back-end texture was created
### Example
### See Also
MakeFromTexture[2] makeTextureImage
---
To be deprecated soon.
enum LegacyBitmapMode {
kRO_LegacyBitmapMode,
};
### Constants
---
bool asLegacyBitmap(SkBitmap* bitmap, LegacyBitmapMode legacyBitmapMode = kRO LegacyBitmapMode) const
Creates raster Bitmap with same pixels as Image. If legacyBitmapMode is
kRO LegacyBitmapMode, returned bitmap is read-only and immutable.
Returns true if Bitmap is stored in bitmap. Returns false and resets bitmap if
Bitmap write did not succeed.
### Parameters
### Return Value
true if Bitmap was created
### Example
### See Also
MakeRasterData makeRasterImage makeNonTextureImage
---
bool isLazyGenerated() const
Returns true if Image is backed by an image-generator or other service that creates
and caches its pixels or texture on-demand.
### Return Value
true if Image is created as needed
### Example
### Example
### See Also
isTextureBacked MakeNonTextureImage
---
sk sp<SkImage> makeColorSpace(sk sp<SkColorSpace> target) const
Creates Image in target Color Space.
Returns nullptr if Image could not be created.
Returns original Image if it is in target Color Space.
Otherwise, converts pixels from Image Color Space to target Color Space.
If Image colorSpace returns nullptr, Image Color Space is assumed to be sRGB.
### Parameters
### Return Value
created Image in target Color Space
### Example
### See Also
MakeFromPixture MakeFromTexture[2]