skia2/site/user/api/SkImage_Reference.md

SkImage Reference

Image

Class SkImage

Image describes a two dimensional array of pixels to draw. The pixels may be unencoded 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 encodings details vary with platform.

Raster Image

Raster Image pixels are unencoded 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

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

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.

Overview

Subtopics

topics	description

Member Functions

description	function
MakeBackendTextureFromSkImage	Creates GPU Texture from Image.
MakeCrossContextFromEncoded	Creates Image from encoded data, and uploads to GPU.
MakeFromAHardwareBuffer	Creates Image from Android hardware buffer.
MakeFromAdoptedTexture	Creates Image from GPU Texture, managed internally.
MakeFromBitmap	Creates Image from Bitmap, sharing or copying pixels.
MakeFromDeferredTextureImageData
MakeFromEncoded	Creates Image from encoded data.
MakeFromGenerator	Creates Image from a stream of data.
MakeFromNV12TexturesCopy	Creates Image from YUV ColorSpace data in two planes.
MakeFromPicture	Creates Image from Picture.
MakeFromRaster	Creates Image from Pixmap, with release.
MakeFromTexture	Creates Image from GPU Texture, managed externally.
MakeFromYUVTexturesCopy	Creates Image from YUV ColorSpace data in three planes.
MakeRasterCopy	Creates Image from Pixmap and copied pixels.
MakeRasterData	Creates Image from Image Info and shared pixels.
alphaType	Returns Alpha Type.
asLegacyBitmap	Returns as Raster Bitmap.
bounds	Returns width and height as Rectangle.
colorSpace	Returns Color Space.
dimensions	Returns width and height.
encodeToData	Returns encoded Image as SkData.
getDeferredTextureImageData
getTexture	Deprecated.
getTextureHandle	Returns GPU reference to Image as texture.
height	Returns pixel row count.
isAlphaOnly	Returns if pixels represent a transparency mask.
isLazyGenerated	Returns if Image is created as needed.
isOpaque	Returns if Alpha Type is kOpaque SkAlphaType.
isTextureBacked	Returns if Image was created from GPU Texture.
isValid	Returns if Image can draw to Raster Surface or GPU Context.
makeColorSpace	Creates Image matching Color Space if possible.
makeNonTextureImage	Creates Image without dependency on GPU Texture.
makeRasterImage	Creates Image compatible with Raster Surface if possible.
makeShader	Creates Shader, Paint element that can tile Image.
makeSubset	Creates Image containing part of original.
makeTextureImage	Creates Image matching Color Space if possible.
makeWithFilter	Creates filtered, clipped Image.
peekPixels	Returns Pixmap if possible.
readPixels	Copies and converts pixels.
refColorSpace	Returns Image Info Color Space.
refEncodedData	Returns Image encoded in SkData if present.
scalePixels	Scales and converts one Image to another.
toString	Converts Image to machine readable form.
uniqueID	Identifier for Image.
width	Returns pixel column count.

MakeRasterCopy

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

pixmap

Image Info, pixel address, and row bytes

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.

See Also

MakeRasterData MakeFromGenerator

---

MakeRasterData

static sk_sp<SkImage> MakeRasterData(const Info& 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

info	contains width, height, Alpha Type, Color Type, Color Space
pixels	address or pixel storage
rowBytes	size of pixel row or larger

Return Value

Image sharing pixels, or nullptr

Example

See Also

MakeRasterCopy MakeFromGenerator

---

Caller data passed to RasterReleaseProc; may be nullptr.

See Also

MakeFromRaster RasterReleaseProc

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

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

pixmap	Image Info, pixel address, and row bytes
rasterReleaseProc	function called when pixels can be released; or nullptr
releaseContext	state passed to rasterReleaseProc; or nullptr

Return Value

Image sharing pixmap

Example

Example Output

before reset: 0
after reset: 1

See Also

MakeRasterCopy MakeRasterData MakeFromGenerator RasterReleaseProc ReleaseContext

---

MakeFromBitmap

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

bitmap

Image Info, row bytes, and pixels

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.

See Also

MakeFromRaster MakeRasterCopy MakeFromGenerator MakeRasterData

---

MakeFromGenerator

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

imageGenerator	stock or custom routines to retrieve Image
subset	bounds of returned Image; may be nullptr

Return Value

created Image, or nullptr

Example

The generator returning Picture cannot be shared; std::move transfers ownership to generated Image.

See Also

MakeFromEncoded

---

MakeFromEncoded

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 platfrom.

Parameters

encoded	data of Image to decode
subset	bounds of returned Image; may be nullptr

Return Value

created Image, or nullptr

Example

See Also

MakeFromGenerator

---

MakeFromTexture

static sk_sp<SkImage> MakeFromTexture(GrContext* context, const GrBackendTexture& backendTexture,
                                      GrSurfaceOrigin origin, SkAlphaType alphaType,
                                      sk_sp<SkColorSpace> colorSpace)

Deprecated.

Parameters

context	GPU Context
backendTexture	texture residing on GPU
origin	one of: kBottomLeft GrSurfaceOrigin, kTopLeft GrSurfaceOrigin
alphaType	one of: kUnknown SkAlphaType, kOpaque SkAlphaType, kPremul SkAlphaType, kUnpremul SkAlphaType
colorSpace	range of colors; may be nullptr

Return Value

created Image, or nullptr

See Also

MakeFromAdoptedTexture SkSurface::MakeFromBackendTexture

---

static sk_sp<SkImage> MakeFromTexture(GrContext* context, const GrBackendTexture& backendTexture,
                                      GrSurfaceOrigin origin, SkAlphaType alphaType,
                                      sk_sp<SkColorSpace> colorSpace,
                                      TextureReleaseProc textureReleaseProc,
                                      ReleaseContext releaseContext)

Deprecated.

Parameters

context	GPU Context
backendTexture	texture residing on GPU
origin	one of: kBottomLeft GrSurfaceOrigin, kTopLeft GrSurfaceOrigin
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

See Also

MakeFromAdoptedTexture SkSurface::MakeFromBackendTexture

---

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, kBGRA 8888 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.

See Also

MakeFromAdoptedTexture SkSurface::MakeFromBackendTexture

---

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, kBGRA 8888 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

---

MakeCrossContextFromEncoded

static sk_sp<SkImage> MakeCrossContextFromEncoded(GrContext* context, sk_sp<SkData> data,
                                                  bool buildMips, SkColorSpace* dstColorSpace)

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

context	GPU Context
data	Image to decode
buildMips	create Image as Mip Map if true
dstColorSpace	range of colors of matching Surface on GPU

Return Value

created Image, or nullptr

Example

See Also

MakeCrossContextFromPixmap

---

MakeCrossContextFromPixmap

static sk_sp<SkImage> MakeCrossContextFromPixmap(GrContext* context, const SkPixmap& pixmap,
                                                 bool buildMips, SkColorSpace* dstColorSpace)

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

context	GPU Context
pixmap	Image Info, pixel address, and row bytes
buildMips	create Image as Mip Map if true
dstColorSpace	range of colors of matching Surface on GPU

Return Value

created Image, or nullptr

Example

See Also

MakeCrossContextFromEncoded

---

MakeFromAdoptedTexture

static sk_sp<SkImage> MakeFromAdoptedTexture(GrContext* context,
                                             const GrBackendTexture& backendTexture,
                                             GrSurfaceOrigin surfaceOrigin,
                                             SkAlphaType alphaType = kPremul_SkAlphaType,
                                             sk_sp<SkColorSpace> colorSpace = nullptr)

Deprecated.

Parameters

context	GPU Context
backendTexture	texture residing on GPU
surfaceOrigin	one of: kBottomLeft GrSurfaceOrigin, kTopLeft GrSurfaceOrigin
alphaType	one of: kUnknown SkAlphaType, kOpaque SkAlphaType, kPremul SkAlphaType, kUnpremul SkAlphaType
colorSpace	range of colors; may be nullptr

Return Value

created Image, or nullptr

See Also

MakeFromTexture MakeFromYUVTexturesCopy

---

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, kBGRA 8888 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 MakeFromYUVTexturesCopy

---

MakeFromYUVTexturesCopy

static sk_sp<SkImage> MakeFromYUVTexturesCopy(GrContext* context, SkYUVColorSpace yuvColorSpace,
                                              const GrBackendObject yuvTextureHandles[3],
                                              const SkISize yuvSizes[3],
                                              GrSurfaceOrigin surfaceOrigin,
                                              sk_sp<SkColorSpace> colorSpace = nullptr)

Creates Image from copy of yuvTextureHandles, an array of textures on GPU. yuvTextureHandles contain pixels for YUV planes of Image. yuvSizes conain dimensions for each pixel plane. Dimensions must be greater than zero but may differ from plane to plane. Returned Image has the dimensions yuvSizes[0]. yuvColorSpace describes how YUV colors convert to RGB colors.

Parameters

context	GPU Context
yuvColorSpace	one of: kJPEG SkYUVColorSpace, kRec601 SkYUVColorSpace, kRec709 SkYUVColorSpace
yuvTextureHandles	array of YUV textures on GPU
yuvSizes	dimensions of YUV textures
surfaceOrigin	one of: kBottomLeft GrSurfaceOrigin, kTopLeft GrSurfaceOrigin
colorSpace	range of colors; may be nullptr

Return Value

created Image, or nullptr

See Also

MakeFromNV12TexturesCopy

---

static sk_sp<SkImage> MakeFromYUVTexturesCopy(GrContext* context, SkYUVColorSpace yuvColorSpace,
                                              const GrBackendTexture yuvTextureHandles[3],
                                              const SkISize yuvSizes[3],
                                              GrSurfaceOrigin surfaceOrigin,
                                              sk_sp<SkColorSpace> colorSpace = nullptr)

Creates Image from copy of yuvTextureHandles, an array of textures on GPU. yuvTextureHandles contain pixels for YUV planes of Image. yuvSizes conain dimensions for each pixel plane. Dimensions must be greater than zero but may differ from plane to plane. Returned Image has the dimensions yuvSizes[0]. yuvColorSpace describes how YUV colors convert to RGB colors.

Parameters

context	GPU Context
yuvColorSpace	one of: kJPEG SkYUVColorSpace, kRec601 SkYUVColorSpace, kRec709 SkYUVColorSpace
yuvTextureHandles	array of YUV textures on GPU
yuvSizes	dimensions of YUV textures
surfaceOrigin	one of: kBottomLeft GrSurfaceOrigin, kTopLeft GrSurfaceOrigin
colorSpace	range of colors; may be nullptr

Return Value

created Image, or nullptr

See Also

MakeFromNV12TexturesCopy

---

MakeFromNV12TexturesCopy

static sk_sp<SkImage> MakeFromNV12TexturesCopy(GrContext* context, SkYUVColorSpace yuvColorSpace,
                                               const GrBackendObject nv12TextureHandles[2],
                                               const SkISize nv12Sizes[2],
                                               GrSurfaceOrigin surfaceOrigin,
                                               sk_sp<SkColorSpace> colorSpace = nullptr)

Creates Image from copy of nv12TextureHandles, an array of textures on GPU. nv12TextureHandles[0] contains pixels for YUV Component Y plane. nv12TextureHandles[1] contains pixels for YUV Component U plane, followed by pixels for YUV Component V plane. nv12Sizes conain dimensions for each pixel plane. Dimensions must be greater than zero but may differ from plane to plane. Returned Image has the dimensions nv12Sizes[0]. yuvColorSpace describes how YUV colors convert to RGB colors.

Parameters

context	GPU Context
yuvColorSpace	one of: kJPEG SkYUVColorSpace, kRec601 SkYUVColorSpace, kRec709 SkYUVColorSpace
nv12TextureHandles	array of YUV textures on GPU
nv12Sizes	dimensions of YUV textures
surfaceOrigin	one of: kBottomLeft GrSurfaceOrigin, kTopLeft GrSurfaceOrigin
colorSpace	range of colors; may be nullptr

Return Value

created Image, or nullptr

See Also

MakeFromYUVTexturesCopy

---

static sk_sp<SkImage> MakeFromNV12TexturesCopy(GrContext* context, SkYUVColorSpace yuvColorSpace,
                                               const GrBackendTexture nv12TextureHandles[2],
                                               const SkISize nv12Sizes[2],
                                               GrSurfaceOrigin surfaceOrigin,
                                               sk_sp<SkColorSpace> colorSpace = nullptr)

Creates Image from copy of nv12TextureHandles, an array of textures on GPU. nv12TextureHandles[0] contains pixels for YUV Component Y plane. nv12TextureHandles[1] contains pixels for YUV Component U plane, followed by pixels for YUV Component V plane. nv12Sizes conain dimensions for each pixel plane. Dimensions must be greater than zero but may differ from plane to plane. Returned Image has the dimensions nv12Sizes[0]. yuvColorSpace describes how YUV colors convert to RGB colors.

Parameters

context	GPU Context
yuvColorSpace	one of: kJPEG SkYUVColorSpace, kRec601 SkYUVColorSpace, kRec709 SkYUVColorSpace
nv12TextureHandles	array of YUV textures on GPU
nv12Sizes	dimensions of YUV textures
surfaceOrigin	one of: kBottomLeft GrSurfaceOrigin, kTopLeft GrSurfaceOrigin
colorSpace	range of colors; may be nullptr

Return Value

created Image, or nullptr

See Also

MakeFromYUVTexturesCopy

---

Enum SkImage::BitDepth

enum class BitDepth {
kU8,
kF16,
};

Constants

SkImage::kU8	0	Use 8 bits per Color ARGB component using unsigned integer format.
SkImage::kF16	1	Use 16 bits per Color ARGB component using half-precision floating point format.

See Also

MakeFromPicture

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

---

MakeFromAHardwareBuffer

static sk_sp<SkImage> MakeFromAHardwareBuffer(AHardwareBuffer* hardwareBuffer,
                                            SkAlphaType alphaType = kPremul_SkAlphaType,
                                            sk_sp<SkColorSpace> colorSpace = nullptr)

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

hardwareBuffer	AHardwareBuffer Android hardware buffer
alphaType	one of: kUnknown SkAlphaType, kOpaque SkAlphaType, kPremul SkAlphaType, kUnpremul SkAlphaType
colorSpace	range of colors; may be nullptr

Return Value

created Image, or nullptr

See Also

MakeFromRaster

---

width

int width() const

Returns pixel count in each row.

Return Value

pixel width in Image

Example

See Also

dimensions height

---

height

int height() const

Returns pixel row count.

Return Value

pixel height in Image

Example

See Also

dimensions width

---

dimensions

SkISize dimensions() const

Returns ISize { width, height }.

Return Value

integral size of width and height

Example

See Also

height width bounds

---

bounds

SkIRect bounds() const

Returns IRect { 0, 0, width, height }.

Return Value

integral rectangle from origin to width and height

Example

See Also

dimensions

---

uniqueID

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

---

alphaType

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

---

colorSpace

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 a parameter to an Image constructor, or was parsed from encoded data. Color Space may be ignored when drawing Image, and when drawing into Surface constructed with Color Space.

Return Value

Color Space in Image, or nullptr

Example

See Also

incomplete

---

refColorSpace

sk_sp<SkColorSpace> refColorSpace() const

Return Value

incomplete

Example

See Also

incomplete

---

isAlphaOnly

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

See Also

incomplete

---

isOpaque

bool isOpaque() const

Returns if all pixels ignore any Alpha value and are treated as fully opaque.

Return Value

true if Alpha Type is kOpaque SkAlphaType

Example

See Also

incomplete

---

makeShader

sk_sp<SkShader> makeShader(SkShader::TileMode tileMode1, SkShader::TileMode tileMode2,
                           const SkMatrix* localMatrix = nullptr) const

Parameters

tileMode1	incomplete
tileMode2	incomplete
localMatrix	incomplete

Return Value

incomplete

Example

See Also

incomplete

---

sk_sp<SkShader> makeShader(const SkMatrix* localMatrix = nullptr) const

Helper version of

Parameters

localMatrix

incomplete

Return Value

incomplete

Example

See Also

incomplete

---

peekPixels

bool peekPixels(SkPixmap* pixmap) const

If the image has direct access to its pixels (i.e. they are in local RAM) return true, and if not null, return in the pixmap parameter the info about the images pixels. On failure, return false and ignore the pixmap parameter.

Parameters

pixmap

incomplete

Return Value

incomplete

Example

See Also

incomplete

---

getTexture

GrTexture* getTexture() const

Deprecated.

---

isTextureBacked

bool isTextureBacked() const

Returns true if the image is texture backed.

Return Value

incomplete

Example

See Also

incomplete

---

isValid

bool isValid(GrContext* context) const

Returns true if Image can be drawn. If context is nullptr, tests if Image draws on Raster Surface; Otherwise, tests if Image draws on GPU Surface associated with context.

Texture-backed images may become invalid if their underlying GrContext is abandoned. Some generator-backed images may be invalid for CPU and/or GPU.

Parameters

context

GPU Context

Return Value

incomplete

Example

See Also

incomplete

---

getTextureHandle

GrBackendObject getTextureHandle(bool flushPendingGrContextIO, GrSurfaceOrigin* origin = nullptr) const

Retrieves the back-end API handle of texture. If flushPendingGrContextIO is true, complete deferred I/O operations.

If origin in not nullptr, copies location of content drawn into Image.

Parameters

flushPendingGrContextIO	flag to flush outstanding requests
origin	storage for one of: kTopLeft GrSurfaceOrigin, kBottomLeft GrSurfaceOrigin; or nullptr

Return Value

back-end API texture handle

Example

See Also

incomplete

---

Enum SkImage::CachingHint

enum CachingHint {
kAllow CachingHint,
kDisallow CachingHint,
};

Hints to image calls where the system might cache computed intermediates (e.g. the results of decoding or a read-back from the GPU. Passing kAllow CachingHint signals that the system's default behavior is fine. Passing kDisallow CachingHint signals that caching should be avoided.

Constants

SkImage::kAllow_CachingHint	0
SkImage::kDisallow_CachingHint	1

Example

See Also

incomplete

readPixels

bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes, int srcX, int srcY,
                CachingHint cachingHint = kAllow_CachingHint) const

Copy the pixels from the image into the specified buffer (dstPixels + dstRowBytes), converting them into the requested format (dstInfo). The image pixels are read starting at the specified (srcX, srcY) location. dstInfo and (srcX, srcY) offset specifies a source rectangle:

SkRect srcR;
srcR.setXYWH(srcX, srcY, dstInfo.width(), dstInfo.height);

The source rectangle is intersected with the bounds of the image. If this intersection is not empty, then we have two sets of pixels (of equal size). Replace dstPixels with the corresponding Image pixels, performing any Color Type/Alpha Type transformations needed (in the case where Image and dstInfo have different Color Types or Alpha Types). This call can fail, returning false, for several reasons: if source rectangle does not intersect the image bounds; if the requested Color Type/Alpha Type cannot be converted from the image's types.

Parameters

dstInfo	incomplete
dstPixels	incomplete
dstRowBytes	incomplete
srcX	incomplete
srcY	incomplete
cachingHint	incomplete

Return Value

incomplete

Example

See Also

incomplete

---

bool readPixels(const SkPixmap& dst, int srcX, int srcY, CachingHint cachingHint = kAllow_CachingHint) const

Parameters

dst	incomplete
srcX	incomplete
srcY	incomplete
cachingHint	incomplete

Return Value

incomplete

Example

See Also

incomplete

---

scalePixels

bool scalePixels(const SkPixmap& dst, SkFilterQuality filterQuality,
                 CachingHint cachingHint = kAllow_CachingHint) const

Copies Image pixels into dst, converting to dst Color Type and Alpha Type. If the conversion cannot be performed, false is returned. If dst dimensions differ from Image dimensions, Image is scaled, applying filterQuality.

Parameters

dst	incomplete
filterQuality	incomplete
cachingHint	incomplete

Return Value

incomplete

Example

See Also

incomplete

---

encodeToData

sk_sp<SkData> encodeToData(SkEncodedImageFormat encodedImageFormat, int quality) const

Encodes Image pixels, returning result as SkData.

Returns nullptr if encoding fails, or encodedImageFormat is not supported.

Parameters

encodedImageFormat	incomplete
quality	incomplete

Return Value

encoded Image, or nullptr

Example

See Also

incomplete

---

sk_sp<SkData> encodeToData() const

Encodes Image and returns result as SkData. Will reuse existing encoded data if present, as returned by refEncodedData. If encoded data is missing or invalid, Image is encoded as PNG.

Returns nullptr if existing encoded data is missing or invalid and encoding fails.

Return Value

incomplete

Example

See Also

incomplete

---

refEncodedData

sk_sp<SkData> refEncodedData() const

If the image already has its contents in encoded form (e.g. PNG or JPEG), return that as SkData. If the image does not already has its contents in encoded form, return nullptr.

To force the image to return its contents as encoded data, call encodeToData.

Return Value

incomplete

Example

See Also

incomplete

---

toString

const char* toString(SkString* string) const

Parameters

string

incomplete

Return Value

incomplete

Example

See Also

incomplete

---

makeSubset

sk_sp<SkImage> makeSubset(const SkIRect& subset) const

Return a new image that is a subset of this image. The underlying implementation may share the pixels, or it may make a copy. If subset does not intersect the bounds of this image, or the copy/share cannot be made, nullptr will be returned.

Parameters

subset

incomplete

Return Value

incomplete

Example

See Also

incomplete

---

makeTextureImage

sk_sp<SkImage> makeTextureImage(GrContext* context, SkColorSpace* dstColorSpace) const

Ensures that an image is backed by a texture (when GrContext is non-null), suitable for use with surfaces that have the supplied destination color space. If no transformation is required, the returned image may be the same as this image. If this image is from a different GrContext, this will fail.

Parameters

context	GPU Context
dstColorSpace	incomplete

Return Value

incomplete

Example

See Also

incomplete

---

makeNonTextureImage

sk_sp<SkImage> makeNonTextureImage() const

Creates raster Image if Image contains GPU Texture and raster Image , this will make a raster copy of it (or nullptr if reading back the pixels fails). Otherwise, it returns the original image.

Return Value

incomplete

Example

See Also

incomplete

---

makeRasterImage

sk_sp<SkImage> makeRasterImage() const

If the image is texture-backed this will make a raster copy of it (or nullptr if reading back the pixels fails). Otherwise, it returns the original image.

Return Value

incomplete

Example

See Also

incomplete

---

makeWithFilter

sk_sp<SkImage> makeWithFilter(const SkImageFilter* filter, const SkIRect& subset,
                              const SkIRect& clipBounds, SkIRect* outSubset, SkIPoint* offset) const

Apply a given image filter to this image, and return the filtered result. The subset represents the active portion of this image. The return value is similarly an SkImage, with an active subset (outSubset). This is usually used with texture-backed images, where the texture may be approx-match and thus larger than the required size. clipBounds constrains the device-space extent of the image, stored in outSubset. offset is storage, set to the amount to translate the result when drawn. If the result image cannot be created, or the result would be transparent black, null is returned, in which case the offset and outSubset parameters should be ignored by the caller.

Parameters

filter	incomplete
subset	incomplete
clipBounds	incomplete
outSubset	incomplete
offset	incomplete

Return Value

incomplete

Example

See Also

incomplete

---

Struct SkImage::DeferredTextureImageUsageParams

struct DeferredTextureImageUsageParams {
DeferredTextureImageUsageParams(const SkMatrix matrix, const SkFilterQuality quality,
int preScaleMipLevel);
SkMatrix        fMatrix;
SkFilterQuality fQuality;
int             fPreScaleMipLevel;
};

SkMatrix fMatrix

SkFilterQuality fQuality

int fPreScaleMipLevel

DeferredTextureImageUsageParams

DeferredTextureImageUsageParams(const SkMatrix matrix, const SkFilterQuality quality,
                                int preScaleMipLevel)

Parameters

matrix	incomplete
quality	incomplete
preScaleMipLevel	incomplete

Return Value

incomplete

Example

See Also

incomplete

---

Example

See Also

incomplete

getDeferredTextureImageData

size_t getDeferredTextureImageData(const GrContextThreadSafeProxy& contextThreadSafeProxy,
                 const DeferredTextureImageUsageParams deferredTextureImageUsageParams[],
                 int paramCnt, void* buffer, SkColorSpace* dstColorSpace = nullptr,
                 SkColorType dstColorType = kN32_SkColorType) const

This method allows clients to capture the data necessary to turn a SkImage into a texture- backed image. If the original image is codec-backed this will decode into a format optimized for the context represented by the proxy. This method is thread safe with respect to the GrContext whence the proxy came. Clients allocate and manage the storage of the deferred texture data and control its lifetime. No cleanup is required, thus it is safe to simply free the memory out from under the data.

The same method is used both for getting the size necessary for pre-uploaded texture data and for retrieving the data. The params array represents the set of draws over which to optimize the pre-upload data.

When called with a null buffer this returns the size that the client must allocate in order to create deferred texture data for this image (or zero if this is an inappropriate candidate). The buffer allocated by the client should be 8 byte aligned.

When buffer is not null this fills in the deferred texture data for this image in the provided buffer (assuming this is an appropriate candidate image and the buffer is appropriately aligned). Upon success the size written is returned, otherwise 0.

dstColorSpace is the color space of the surface where this texture will ultimately be used. If the method determines that mip-maps are needed, this helps determine the correct strategy for building them (gamma-correct or not).

dstColorType is the color type of the surface where this texture will ultimately be used. This determines the format with which the image will be uploaded to the GPU. If dstColorType does not support color spaces (low bit depth types such as kARGB 4444 SkColorType), then dstColorSpace must be null.

Parameters

contextThreadSafeProxy	incomplete
deferredTextureImageUsageParams	incomplete
paramCnt	incomplete
buffer	incomplete
dstColorSpace	incomplete
dstColorType	incomplete

Return Value

incomplete

Example

See Also

incomplete

---

MakeFromDeferredTextureImageData

static sk_sp<SkImage> MakeFromDeferredTextureImageData(GrContext* context, const void* data,
                                                SkBudgeted budgeted)

Returns a texture-backed image from data produced in SkImage::getDeferredTextureImageData. The context must be the context that provided the proxy passed to getDeferredTextureImageData.

Parameters

context	GPU Context
data	incomplete
budgeted	incomplete

Return Value

incomplete

Example

See Also

incomplete

---

BackendTextureReleaseProc

MakeBackendTextureFromSkImage

static bool MakeBackendTextureFromSkImage(GrContext* context, sk_sp<SkImage> image,
                                          GrBackendTexture* backendTexture,
                                          BackendTextureReleaseProc* backendTextureReleaseProc)

Creates a GrBackendTexture from the provided SkImage. Returns true on success. The GrBackendTexture and BackendTextureReleaseProc are populated on success. It is the callers responsibility to call the BackendTextureReleaseProc once they have deleted the texture. Note that the BackendTextureReleaseProc allows Skia to clean up auxiliary data related to the GrBackendTexture, and is not a substitute for the client deleting the GrBackendTexture themselves.

If image is both texture backed and singly referenced; that is, its only reference was transferred using std::move(): image is returned in backendTexture without conversion or making a copy.

If the SkImage is not texture backed, this function will generate a texture with the image's contents and return that.

Parameters

context	GPU Context
image	incomplete
backendTexture	incomplete
backendTextureReleaseProc	incomplete

Return Value

incomplete

Example

See Also

incomplete

---

Enum SkImage::LegacyBitmapMode

enum LegacyBitmapMode {
kRO LegacyBitmapMode,
kRW LegacyBitmapMode,
};

Helper functions to convert to SkBitmap

Constants

SkImage::kRO_LegacyBitmapMode	0
SkImage::kRW_LegacyBitmapMode	1

Example

See Also

incomplete

asLegacyBitmap

bool asLegacyBitmap(SkBitmap* bitmap, LegacyBitmapMode 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

bitmap	storage for legacy Bitmap
legacyBitmapMode	one of: kRO LegacyBitmapMode, kRW LegacyBitmapMode

Return Value

true if Bitmap was created

Example

See Also

incomplete

---

isLazyGenerated

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

See Also

incomplete

---

makeColorSpace

sk_sp<SkImage> makeColorSpace(sk_sp<SkColorSpace> target, SkTransferFunctionBehavior premulBehavior) const

If target is supported, returns an SkImage in target color space. Otherwise, returns nullptr. This will leave the image as is if it already in target color space. Otherwise, it will convert the pixels from Image color space to target color space. If this->colorSpace is nullptr, Image color space will be treated as sRGB.

If premulBehavior is SkTransferFunctionBehavior::kRespect: converts Image pixels to a linear space before converting to match destination Color Type and Color Space. If premulBehavior is SkTransferFunctionBehavior::kIgnore: Image pixels are treated as if they are linear, regardless of how they are encoded.

Parameters

target	incomplete
premulBehavior	incomplete

Return Value

incomplete

Example

See Also

incomplete

---