more image docs, still not done add ability to comment out non-working examples easily start work on additional self-checks clean up use of this-> in docs TBR=reed@google.com Docs-Preview: https://skia.org/?cl=91720 Bug: skia:6898 Change-Id: I706ab8145290e53ab67d3f509ccf4e1225adb3c3 Reviewed-on: https://skia-review.googlesource.com/91720 Commit-Queue: Cary Clark <caryclark@skia.org> Reviewed-by: Cary Clark <caryclark@skia.org>
122 KiB
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
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
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
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
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
See Also
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
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
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
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
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
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
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
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
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
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
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
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
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
width
int width() const
Returns pixel count in each row.
Return Value
Example
See Also
height
int height() const
Returns pixel row count.
Return Value
Example
See Also
dimensions
SkISize dimensions() const
Returns ISize { width, height }.
Return Value
integral size of width and height
Example
See Also
bounds
SkIRect bounds() const
Returns IRect { 0, 0, width, height }.
Return Value
integral rectangle from origin to width and height
Example
See Also
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
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
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 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
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
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
Example Output
alphaOnly = true
See Also
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
makeShader
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
tileMode1 | tiling in x, one of: SkShader::kClamp TileMode, SkShader::kRepeat TileMode, SkShader::kMirror TileMode |
tileMode2 | tiling in y, one of: SkShader::kClamp TileMode, SkShader::kRepeat TileMode, SkShader::kMirror TileMode |
localMatrix | Image transformation, or nullptr |
Return Value
Example
See Also
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
localMatrix | Image transformation, or nullptr |
Return Value
Example
See Also
peekPixels
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
getTexture
GrTexture* getTexture() const
Deprecated.
isTextureBacked
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
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
context | GPU Context |
Return Value
true if Image can be drawn
Example
See Also
isTextureBacked isLazyGenerated
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, or nullptr
Example
Example
See Also
MakeFromTexture isTextureBacked
Enum SkImage::CachingHint
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
SkImage::kAllow_CachingHint | 0 | Allows Skia to internally cache decoded and copied pixels. |
SkImage::kDisallow_CachingHint | 1 | Disallows Skia from internally caching decoded and copied pixels. |
See Also
readPixels
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:
dstInfo.addr() equals nullptr |
dstRowBytes is less than dstInfo.minRowBytes |
Pixel Ref is nullptr |
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 ifabs(srcX) >= Image width, or ifabs(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
dstInfo | destination width, height, Color Type, Alpha Type, Color Space |
dstPixels | destination pixel storage |
dstRowBytes | destination row length |
srcX | column index whose absolute value is less than width |
srcY | row index whose absolute value is less than height |
cachingHint | one of: kAllow CachingHint, kDisallow CachingHint |
Return Value
true if pixels are copied to dstPixels
Example
See Also
scalePixels SkBitmap::readPixels SkPixmap::readPixels SkCanvas::readPixels SkSurface::readPixels
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:
dst pixel storage equals nullptr |
dst.rowBytes is less than SkImageInfo::minRowBytes |
Pixel Ref is nullptr |
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 ifabs(srcX) >= Image width, or ifabs(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
dst | destination Pixmap: Image Info, pixels, row bytes |
srcX | column index whose absolute value is less than width |
srcY | row index whose absolute value is less than height |
cachingHint | one of: kAllow CachingHint, kDisallow CachingHint |
Return Value
true if pixels are copied to dst
Example
See Also
scalePixels SkBitmap::readPixels SkPixmap::readPixels SkCanvas::readPixels SkSurface::readPixels
scalePixels
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
dst | destination Pixmap: Image Info, pixels, row bytes |
filterQuality | one of: kNone SkFilterQuality, kLow SkFilterQuality, kMedium SkFilterQuality, kHigh SkFilterQuality |
cachingHint | one of: kAllow CachingHint, kDisallow CachingHint |
Return Value
true if pixels are scaled to fit dst
Example
See Also
SkCanvas::drawImage readPixels SkPixmap::scalePixels
encodeToData
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
encodedImageFormat | one of: SkEncodedImageFormat::kJPEG, SkEncodedImageFormat::kPNG, SkEncodedImageFormat::kWEBP |
quality | encoder specific metric with 100 equaling best |
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
refEncodedData
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
toString
const char* toString(SkString* string) const
Appends Image description to string, including unique ID, width, height, and whether the image is opaque.
Parameters
string | storage for description; existing content is preserved |
Return Value
string appended with Image description
Example
See Also
makeSubset
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
subset | bounds of returned Image |
Return Value
partial or full Image, or nullptr
Example
See Also
makeTextureImage
sk_sp<SkImage> makeTextureImage(GrContext* context, SkColorSpace* dstColorSpace) const
Returns Image backed by GPU Texture associated with context. Returned Image is compatible with Surface created with dstColorSpace. Returns original Image if context and dstColorSpace match.
Returns nullptr if context is nullptr, or if Image was created with another GrContext.
Parameters
context | GPU Context |
dstColorSpace | range of colors of matching Surface on GPU |
Return Value
created Image, or nullptr
Example
See Also
makeNonTextureImage
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 unencoded 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
incomplete
makeRasterImage
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 unencoded in Raster Bitmap.
Returns nullptr if copy, decode, or pixel read fails.
Return Value
Raster Image, or nullptr
Example
See Also
isTextureBacked isLazyGenerated MakeFromRaster
makeWithFilter
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.
makeWithFilter is optimized to support Image backed by GPU Texture drawn in an animation with SkImageFilter that vary in size from one frame to the next. The created Image is drawn at an increased size so that GPU Texture can be reused with different sized effects. outSubset describes the valid bounds of GPU Texture returned. The returned Image may be much larger than required for the filter. offset translates the returned Image to keep subsequent animation frames aligned with respect to each other.
Parameters
filter | how Image is sampled when transformed |
subset | incomplete |
clipBounds | incomplete |
outSubset | incomplete |
offset | incomplete |
Return Value
filtered Image, or nullptr
Example
See Also
Struct SkImage::DeferredTextureImageUsageParams
Used only by Chrome; to be deprecated.
struct DeferredTextureImageUsageParams { DeferredTextureImageUsageParams(const SkMatrix matrix, const SkFilterQuality quality, int preScaleMipLevel); 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
Used only by Chrome; to be deprecated.
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 Space (low bit depth types such as kARGB 4444 SkColorType), then dstColorSpace must be null.
Parameters
contextThreadSafeProxy | thread safe GPU context |
deferredTextureImageUsageParams | array of Image transformations |
paramCnt | entries in deferredTextureImageUsageParams array |
buffer | storage for GPU Texture data, or nullptr |
dstColorSpace | Surface Color Space, or nullptr |
dstColorType | Surface Color Type |
Return Value
size of storage for GPU Texture data
Example
See Also
MakeFromDeferredTextureImageData
MakeFromDeferredTextureImageData
static sk_sp<SkImage> MakeFromDeferredTextureImageData(GrContext* context, const void* data, SkBudgeted budgeted)
Used only by Chrome; to be deprecated.
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
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
Example
See Also
isTextureBacked MakeNonTextureImage
makeColorSpace
sk_sp<SkImage> makeColorSpace(sk_sp<SkColorSpace> target, SkTransferFunctionBehavior premulBehavior) 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.
SkTransferFunctionBehavior is to be deprecated.
Set premulBehavior to SkTransferFunctionBehavior::kRespect to convert Image pixels to a linear space, before converting to destination Color Type and Color Space.
Set premulBehavior to SkTransferFunctionBehavior::kIgnore to treat Image pixels as linear, when converting to destination Color Type and Color Space, ignoring pixel encoding.
Parameters
target | Color Space describing color range of returned Image |
premulBehavior | one of: SkTransferFunctionBehavior::kRespect, SkTransferFunctionBehavior::kIgnore |
Return Value
created Image in target Color Space
Example
See Also
MakeFromPixture MakeFromTexture