Cary Clark 682c58da48 Documentation refresh

- add links to types within methods
- add check to see that all references and definitions match
- add style to tables to make them easier to read
- use https everywhere
- remove trailing spaces
- move overview inside class
- split class and struct in summary tables
- add missing #Line
- clean up SkImageInfo constant documentation
- work on SkColor documentation
- allow common phrases to take different parameters
- add more flexibility to generated tables
- tighten token parent requirements
- generalize deprecated and example interfaces
- detect inner constructors

R=caryclark@google.com
Docs-Preview: https://skia.org/?cl=121799
Bug: skia:6898
Change-Id: Ia75a23740b80259460916890b310e2a9f024962a
Reviewed-on: https://skia-review.googlesource.com/121799
Commit-Queue: Cary Clark <caryclark@skia.org>
Auto-Submit: Cary Clark <caryclark@skia.org>
Reviewed-by: Cary Clark <caryclark@skia.org>

2018-05-16 11:35:24 +00:00

SkImage Reference

Image

Class SkImage

Constant

SkImage related constants are defined by enum, enum class, #define, const, and constexpr.

Topic	Description
BitDepth	options for MakeFromPicture
CachingHint	options for readPixels and scalePixels
kAllow CachingHint	allows internally caching decoded and copied pixels
kDisallow CachingHint	disallows internally caching decoded and copied pixels
BitDepth::kF16	uses 16-bit float per Color component
kRO LegacyBitmapMode	returned bitmap is read-only and immutable
BitDepth::kU8	uses 8-bit unsigned int per Color component

Typedef

SkImage typedef define a data type.

Topic	Description
BackendTextureReleaseProc	parameter type for MakeBackendTextureFromSkImage
RasterReleaseProc	parameter type for MakeFromRaster
ReleaseContext	parameter type for MakeFromRaster
TextureReleaseProc	parameter type for MakeFromTexture

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

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

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

Topic	Description
Constants	enum and enum class, and their const values
Constructors	functions that construct SkImage
Functions	global and class member functions
Related Functions	similar member functions grouped together
Typedef Declarations	types defined by other types

Related Function

SkImage global, struct, and class related member functions share a topic.

Topic	Description
Lazy Image	deferred pixel buffer
Pixels	read and write pixel values
Property	values and attributes
Raster Image	pixels decoded in Raster Bitmap
Texture Image	pixels located on GPU
Utility	rarely called management functions

Constructor

SkImage can be constructed or initialized by these functions, including C++ class constructors.

Topic	Description
MakeBackendTextureFromSkImage	creates GPU Texture from Image
MakeCrossContextFromEncoded	creates Image from encoded data, and uploads to GPU
MakeCrossContextFromPixmap	creates Image from Pixmap, 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
MakeFromEncoded	creates Image from encoded data
MakeFromGenerator	creates Image from a stream of data
MakeFromNV12TexturesCopy	creates Image from YUV ColorSpace data in three planes
MakeFromPicture	creates Image from Picture
MakeFromRaster	creates Image from Pixmap, with release
MakeFromTexture	creates Image from GPU Texture
	MakeFromTexture(GrContext* context, const GrBackendTexture& backendTexture, GrSurfaceOrigin origin, SkColorType colorType, SkAlphaType alphaType, sk sp<SkColorSpace> colorSpace)
	MakeFromTexture(GrContext* context, const GrBackendTexture& backendTexture, GrSurfaceOrigin origin, SkColorType colorType, SkAlphaType alphaType, sk sp<SkColorSpace> colorSpace, TextureReleaseProc textureReleaseProc, ReleaseContext releaseContext)
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
asLegacyBitmap	returns as Raster Bitmap
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
	makeShader(SkShader::TileMode tileMode1, SkShader::TileMode tileMode2, const SkMatrix* localMatrix = nullptr) const
	makeShader(const SkMatrix* localMatrix = nullptr) const
makeSubset	creates Image containing part of original
makeTextureImage	creates Image matching Color Space if possible
makeWithFilter	creates filtered, clipped Image

Member Function

SkImage member functions read and modify the structure properties.

Topic	Description
MakeBackendTextureFromSkImage	creates GPU Texture from Image
MakeCrossContextFromEncoded	creates Image from encoded data, and uploads to GPU
MakeCrossContextFromPixmap	creates Image from Pixmap, 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
MakeFromEncoded	creates Image from encoded data
MakeFromGenerator	creates Image from a stream of data
MakeFromNV12TexturesCopy	creates Image from YUV ColorSpace data in three planes
MakeFromPicture	creates Image from Picture
MakeFromRaster	creates Image from Pixmap, with release
MakeFromTexture	creates Image from GPU Texture
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
colorType	returns Color Type
dimensions	returns width and height
encodeToData	returns encoded Image as SkData
getBackendTexture	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	returns 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.

MakeRasterData

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

`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

Typedef SkImage::ReleaseContext

Caller data passed to RasterReleaseProc; may be nullptr.

Typedef SkImage::RasterReleaseProc

Function called when Image no longer shares pixels. ReleaseContext is provided by caller when Image is created, and may be nullptr.

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

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.

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.

Parameters

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

Return Value

created Image, or nullptr

Example

Typedef SkImage::TextureReleaseProc

User function called when supplied texture may be deleted.

MakeFromTexture

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.

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

MakeCrossContextFromEncoded

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

`context`	GPU Context
`data`	Image to decode
`buildMips`	create Image as Mip_Map if true
`dstColorSpace`	range of colors of matching Surface on GPU
`limitToMaxTextureSize`	downscale image to GPU maximum texture size, if necessary

Return Value

created Image, or nullptr

Example

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
`limitToMaxTextureSize`	downscale image to GPU maximum texture size, if necessary

Return Value

created Image, or nullptr

Example

MakeFromAdoptedTexture

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

MakeFromYUVTexturesCopy

static sk sp<SkImage> MakeFromYUVTexturesCopy(GrContext* context, SkYUVColorSpace yuvColorSpace,
                                              const GrBackendTexture yuvTextures[3],
                                              GrSurfaceOrigin surfaceOrigin,
                                              sk sp<SkColorSpace> colorSpace = 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

`context`	GPU Context
`yuvColorSpace`	one of: kJPEG_SkYUVColorSpace, kRec601_SkYUVColorSpace, kRec709_SkYUVColorSpace
`yuvTextures`	array of YUV textures on GPU
`surfaceOrigin`	one of: kBottomLeft GrSurfaceOrigin, kTopLeft GrSurfaceOrigin
`colorSpace`	range of colors; may be nullptr

Return Value

created Image, or nullptr

Parameters

`context`	GPU Context
`yuvColorSpace`	one of: kJPEG_SkYUVColorSpace, kRec601_SkYUVColorSpace, kRec709_SkYUVColorSpace
`nv12Textures`	array of YUV textures on GPU
`surfaceOrigin`	one of: kBottomLeft GrSurfaceOrigin, kTopLeft GrSurfaceOrigin
`colorSpace`	range of colors; may be nullptr

Return Value

created Image, or nullptr

Enum SkImage::BitDepth

    enum class BitDepth {
        kU8,
        kF16,
    };

Constants

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

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

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

Property

Topic	Description
alphaType	returns Alpha Type
bounds	returns width and height as Rectangle
colorSpace	returns Color Space
colorType	returns Color Type
dimensions	returns width and height
getBackendTexture	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
refColorSpace	returns Image Info Color Space
uniqueID	returns identifier for Image
width	returns pixel column count

width

int width() const

Returns pixel count in each row.

Return Value

pixel width in Image

Example

height

int height() const

Returns pixel row count.

Return Value

pixel height in Image

Example

dimensions

SkISize dimensions() const

Returns ISize { width, height }.

Return Value

integral size of width and height

Example

Example Output

dimensionsAsBounds == bounds

bounds

SkIRect bounds() const

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

Return Value

integral rectangle from origin to width and height

Example

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

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

colorType

SkColorType colorType() const

Returns Color Type if known; otherwise, returns kUnknown_SkColorType.

Return Value

Color Type of Image

Example

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

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.

Return Value

Color Space in Image, or nullptr, wrapped in a smart pointer

Example

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

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

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

Shader containing Image

Example

Parameters

localMatrix Image transformation, or nullptr

Return Value

Shader containing Image

Example

Pixels

Topic	Description
peekPixels	returns Pixmap if possible
readPixels	copies and converts pixels
	readPixels(const SkImageInfo& dstInfo, void* dstPixels, size t dstRowBytes, int srcX, int srcY, CachingHint cachingHint = kAllow CachingHint) const
	readPixels(const SkPixmap& dst, int srcX, int srcY, CachingHint cachingHint = kAllow CachingHint) const
scalePixels	scales and converts one Image to another

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

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

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

getTextureHandle

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

Deprecated.

getBackendTexture

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

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

Return Value

back-end API texture handle; invalid on failure

Example

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

Const	Value	Description
`SkImage::kAllow_CachingHint`	0	allows internally caching decoded and copied pixels
`SkImage::kDisallow_CachingHint`	1	disallows internally caching decoded and copied pixels

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

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

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.

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

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

Return Value

encoded Image, or nullptr

Example

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

Utility

Topic	Description
encodeToData	returns encoded Image as SkData
	encodeToData(SkEncodedImageFormat encodedImageFormat, int quality) const
	encodeToData const
refEncodedData	returns Image encoded in SkData if present
toString	converts Image to machine readable form

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

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

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

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

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 decoded in Raster Bitmap.

Returns nullptr if copy, decode, or pixel read fails.

Return Value

Raster Image, or nullptr

Example

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.

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

`filter`	how Image is sampled when transformed
`subset`	bounds of Image processed by filter
`clipBounds`	expected bounds of filtered Image
`outSubset`	storage for returned Image bounds
`offset`	storage for returned Image translation

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 SkImage::BackendTextureReleaseProc

BackendTextureReleaseProcDefines a function take one parameter of type GrBackendTexture with no return value.

MakeBackendTextureFromSkImage

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

`context`	GPU Context
`image`	Image used for texture
`backendTexture`	storage for back-end texture
`backendTextureReleaseProc`	storage for clean up function

Return Value

true if back-end texture was created

Example

Enum SkImage::LegacyBitmapMode

Deprecated.

soon

    enum LegacyBitmapMode {
        kRO LegacyBitmapMode,
    };

Constants

Const	Value	Description
`SkImage::kRO_LegacyBitmapMode`	0	returned bitmap is read-only and immutable

asLegacyBitmap

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

`bitmap`	storage for legacy Bitmap
`legacyBitmapMode`	to be deprecated

Return Value

true if Bitmap was created

Example

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

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

153 KiB Raw Blame History

SkImage Reference

Overview

MakeRasterCopy

Parameters

Return Value

Example

See Also

MakeRasterData

Parameters

Return Value

Example

See Also

See Also

See Also

MakeFromRaster

Parameters

Return Value

Example

Example Output

See Also

MakeFromBitmap

Parameters

Return Value

Example

See Also

MakeFromGenerator

Parameters

Return Value

Example

See Also

MakeFromEncoded

Parameters

Return Value

Example

See Also

See Also

MakeFromTexture

Parameters

Return Value

Example

See Also

Parameters

Return Value

Example

See Also

MakeCrossContextFromEncoded

Parameters

Return Value

Example

See Also

MakeCrossContextFromPixmap

Parameters

Return Value

Example

See Also

MakeFromAdoptedTexture

Parameters

Return Value

Example

See Also

MakeFromYUVTexturesCopy

Parameters

Return Value

See Also

MakeFromNV12TexturesCopy

Parameters

Return Value

See Also

Constants

See Also

MakeFromPicture

Parameters

Return Value

Example

See Also

MakeFromAHardwareBuffer

Parameters

Return Value

See Also

153 KiB

Raw Blame History