SkImage describes a two dimensional array of pixels to draw. More...

#include <SkImage.h>

Inheritance diagram for SkImage:

Classes
class	AsyncReadResult
	The result from asyncRescaleAndReadPixels() or asyncRescaleAndReadPixelsYUV420(). More...

struct	RequiredProperties

Public Types
enum	CachingHint { kAllow_CachingHint , kDisallow_CachingHint }

enum class	RescaleGamma : bool { kSrc , kLinear }

enum class	RescaleMode { kNearest , kLinear , kRepeatedLinear , kRepeatedCubic }

enum	LegacyBitmapMode { kRO_LegacyBitmapMode }
	Deprecated. More...

using	ReadPixelsContext = void *
	Client-provided context that is passed to client-provided ReadPixelsContext. More...

using	ReadPixelsCallback = void(ReadPixelsContext, std::unique_ptr< const AsyncReadResult >)
	Client-provided callback to asyncRescaleAndReadPixels() or asyncRescaleAndReadPixelsYUV420() that is called when read result is ready or on failure. More...

Public Member Functions
const SkImageInfo &	imageInfo () const
	Returns a SkImageInfo describing the width, height, color type, alpha type, and color space of the SkImage. More...

int	width () const
	Returns pixel count in each row. More...

int	height () const
	Returns pixel row count. More...

SkISize	dimensions () const
	Returns SkISize { width(), height() }. More...

SkIRect	bounds () const
	Returns SkIRect { 0, 0, width(), height() }. More...

uint32_t	uniqueID () const
	Returns value unique to image. More...

SkAlphaType	alphaType () const
	Returns SkAlphaType. More...

SkColorType	colorType () const
	Returns SkColorType if known; otherwise, returns kUnknown_SkColorType. More...

SkColorSpace *	colorSpace () const
	Returns SkColorSpace, the range of colors, associated with SkImage. More...

sk_sp< SkColorSpace >	refColorSpace () const
	Returns a smart pointer to SkColorSpace, the range of colors, associated with SkImage. More...

bool	isAlphaOnly () const
	Returns true if SkImage pixels represent transparency only. More...

bool	isOpaque () const
	Returns true if pixels ignore their alpha value and are treated as fully opaque. More...

sk_sp< SkShader >	makeShader (SkTileMode tmx, SkTileMode tmy, const SkSamplingOptions &, const SkMatrix *localMatrix=nullptr) const
	Make a shader with the specified tiling and mipmap sampling. More...

sk_sp< SkShader >	makeShader (SkTileMode tmx, SkTileMode tmy, const SkSamplingOptions &sampling, const SkMatrix &lm) const

sk_sp< SkShader >	makeShader (const SkSamplingOptions &sampling, const SkMatrix &lm) const
	Defaults to clamp in both X and Y. More...

sk_sp< SkShader >	makeShader (const SkSamplingOptions &sampling, const SkMatrix *lm=nullptr) const

sk_sp< SkShader >	makeRawShader (SkTileMode tmx, SkTileMode tmy, const SkSamplingOptions &, const SkMatrix *localMatrix=nullptr) const
	makeRawShader functions like makeShader, but for images that contain non-color data. More...

sk_sp< SkShader >	makeRawShader (SkTileMode tmx, SkTileMode tmy, const SkSamplingOptions &sampling, const SkMatrix &lm) const

sk_sp< SkShader >	makeRawShader (const SkSamplingOptions &sampling, const SkMatrix &lm) const
	Defaults to clamp in both X and Y. More...

sk_sp< SkShader >	makeRawShader (const SkSamplingOptions &sampling, const SkMatrix *lm=nullptr) const

bool	peekPixels (SkPixmap *pixmap) const
	Copies SkImage pixel address, row bytes, and SkImageInfo to pixmap, if address is available, and returns true. More...

virtual bool	isTextureBacked () const =0
	Returns true if the contents of SkImage was created on or uploaded to GPU memory, and is available as a GPU texture. More...

virtual size_t	textureSize () const =0
	Returns an approximation of the amount of texture memory used by the image. More...

virtual bool	isValid (GrRecordingContext *context) const =0
	Returns true if SkImage can be drawn on either raster surface or GPU surface. More...

bool	readPixels (GrDirectContext context, const SkImageInfo &dstInfo, void dstPixels, size_t dstRowBytes, int srcX, int srcY, CachingHint cachingHint=kAllow_CachingHint) const
	Copies SkRect of pixels from SkImage to dstPixels. More...

bool	readPixels (GrDirectContext *context, const SkPixmap &dst, int srcX, int srcY, CachingHint cachingHint=kAllow_CachingHint) const
	Copies a SkRect of pixels from SkImage to dst. More...

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

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

void	asyncRescaleAndReadPixels (const SkImageInfo &info, const SkIRect &srcRect, RescaleGamma rescaleGamma, RescaleMode rescaleMode, ReadPixelsCallback callback, ReadPixelsContext context) const
	Makes image pixel data available to caller, possibly asynchronously. More...

void	asyncRescaleAndReadPixelsYUV420 (SkYUVColorSpace yuvColorSpace, sk_sp< SkColorSpace > dstColorSpace, const SkIRect &srcRect, const SkISize &dstSize, RescaleGamma rescaleGamma, RescaleMode rescaleMode, ReadPixelsCallback callback, ReadPixelsContext context) const
	Similar to asyncRescaleAndReadPixels but performs an additional conversion to YUV. More...

void	asyncRescaleAndReadPixelsYUVA420 (SkYUVColorSpace yuvColorSpace, sk_sp< SkColorSpace > dstColorSpace, const SkIRect &srcRect, const SkISize &dstSize, RescaleGamma rescaleGamma, RescaleMode rescaleMode, ReadPixelsCallback callback, ReadPixelsContext context) const
	Identical to asyncRescaleAndReadPixelsYUV420 but a fourth plane is returned in the AsyncReadResult passed to 'callback'. More...

bool	scalePixels (const SkPixmap &dst, const SkSamplingOptions &, CachingHint cachingHint=kAllow_CachingHint) const
	Copies SkImage to dst, scaling pixels to fit dst.width() and dst.height(), and converting pixels to match dst.colorType() and dst.alphaType(). More...

sk_sp< SkData >	refEncodedData () const
	Returns encoded SkImage pixels as SkData, if SkImage was created from supported encoded stream format. More...

virtual sk_sp< SkImage >	makeSubset (GrDirectContext *direct, const SkIRect &subset) const =0
	Returns subset of this image. More...

virtual sk_sp< SkImage >	makeSubset (skgpu::graphite::Recorder *, const SkIRect &subset, RequiredProperties) const =0
	Returns subset of this image. More...

bool	hasMipmaps () const
	Returns true if the image has mipmap levels. More...

bool	isProtected () const
	Returns true if the image holds protected content. More...

sk_sp< SkImage >	withDefaultMipmaps () const
	Returns an image with the same "base" pixels as the this image, but with mipmap levels automatically generated and attached. More...

sk_sp< SkImage >	makeNonTextureImage (GrDirectContext *=nullptr) const
	Returns raster image or lazy image. More...

sk_sp< SkImage >	makeRasterImage (GrDirectContext *, CachingHint cachingHint=kDisallow_CachingHint) const
	Returns raster image. More...

sk_sp< SkImage >	makeRasterImage (CachingHint cachingHint=kDisallow_CachingHint) const

bool	asLegacyBitmap (SkBitmap *bitmap, LegacyBitmapMode legacyBitmapMode=kRO_LegacyBitmapMode) const
	Deprecated. More...

virtual bool	isLazyGenerated () const =0
	Returns true if SkImage is backed by an image-generator or other service that creates and caches its pixels or texture on-demand. More...

virtual sk_sp< SkImage >	makeColorSpace (GrDirectContext *direct, sk_sp< SkColorSpace > target) const =0
	Creates SkImage in target SkColorSpace. More...

virtual sk_sp< SkImage >	makeColorSpace (skgpu::graphite::Recorder *, sk_sp< SkColorSpace > targetColorSpace, RequiredProperties) const =0
	Creates SkImage in target SkColorSpace. More...

virtual sk_sp< SkImage >	makeColorTypeAndColorSpace (GrDirectContext *direct, SkColorType targetColorType, sk_sp< SkColorSpace > targetCS) const =0
	Experimental. More...

virtual sk_sp< SkImage >	makeColorTypeAndColorSpace (skgpu::graphite::Recorder *, SkColorType targetColorType, sk_sp< SkColorSpace > targetColorSpace, RequiredProperties) const =0
	Experimental. More...

sk_sp< SkImage >	reinterpretColorSpace (sk_sp< SkColorSpace > newColorSpace) const
	Creates a new SkImage identical to this one, but with a different SkColorSpace. More...

bool	unique () const
	May return true if the caller is the only owner. More...

void	ref () const
	Increment the reference count. More...

void	unref () const
	Decrement the reference count. More...

Friends
class	SkBitmap

class	SkImage_Base

class	SkImage_Raster

class	SkMipmapBuilder

Detailed Description

SkImage describes a two dimensional array of pixels to draw.

The pixels may be decoded in a raster bitmap, encoded in a SkPicture or compressed data stream, or located in GPU memory as a GPU texture.

SkImage cannot be modified after it is created. SkImage may allocate additional storage as needed; for instance, an encoded SkImage may decode when drawn.

SkImage width and height are greater than zero. Creating an SkImage with zero width or height returns SkImage equal to nullptr.

SkImage may be created from SkBitmap, SkPixmap, SkSurface, SkPicture, 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.

See SkImages namespace for the static factory methods to make SkImages.

Clients should not subclass SkImage as there is a lot of internal machinery that is not publicly accessible.

Member Typedef Documentation

◆ ReadPixelsCallback

using SkImage::ReadPixelsCallback = void(ReadPixelsContext, std::unique_ptr<const AsyncReadResult>)

Client-provided callback to asyncRescaleAndReadPixels() or asyncRescaleAndReadPixelsYUV420() that is called when read result is ready or on failure.

◆ ReadPixelsContext

using SkImage::ReadPixelsContext = void*

Client-provided context that is passed to client-provided ReadPixelsContext.

Member Enumeration Documentation

◆ CachingHint

enum SkImage::CachingHint

Enumerator
kAllow_CachingHint	allows internally caching decoded and copied pixels
kDisallow_CachingHint	disallows internally caching decoded and copied pixels

◆ LegacyBitmapMode

enum SkImage::LegacyBitmapMode

Deprecated.

Enumerator
kRO_LegacyBitmapMode	returned bitmap is read-only and immutable

◆ RescaleGamma

enum SkImage::RescaleGamma : bool

strong

Enumerator
kSrc
kLinear

◆ RescaleMode

enum SkImage::RescaleMode

strong

Enumerator
kNearest
kLinear
kRepeatedLinear
kRepeatedCubic

Member Function Documentation

◆ alphaType()

SkAlphaType SkImage::alphaType ( ) const

Returns SkAlphaType.

SkAlphaType returned was a parameter to an SkImage constructor, or was parsed from encoded data.

Returns: SkAlphaType in SkImage

example: https://fiddle.skia.org/c/@Image_alphaType

◆ asLegacyBitmap()

bool SkImage::asLegacyBitmap	(	SkBitmap *	bitmap,
		LegacyBitmapMode	legacyBitmapMode = `kRO_LegacyBitmapMode`
	)		const

Deprecated.

Creates raster SkBitmap with same pixels as SkImage. If legacyBitmapMode is kRO_LegacyBitmapMode, returned bitmap is read-only and immutable. Returns true if SkBitmap is stored in bitmap. Returns false and resets bitmap if SkBitmap write did not succeed.

Parameters

bitmap	storage for legacy SkBitmap
legacyBitmapMode	bitmap is read-only and immutable

Returns: true if SkBitmap was created

◆ asyncRescaleAndReadPixels()

void SkImage::asyncRescaleAndReadPixels	(	const SkImageInfo &	info,
		const SkIRect &	srcRect,
		RescaleGamma	rescaleGamma,
		RescaleMode	rescaleMode,
		ReadPixelsCallback	callback,
		ReadPixelsContext	context
	)		const

Makes image pixel data available to caller, possibly asynchronously.

It can also rescale the image pixels.

Currently asynchronous reads are only supported on the GPU backend and only when the underlying 3D API supports transfer buffers and CPU/GPU synchronization primitives. In all other cases this operates synchronously.

Data is read from the source sub-rectangle, is optionally converted to a linear gamma, is rescaled to the size indicated by 'info', is then converted to the color space, color type, and alpha type of 'info'. A 'srcRect' that is not contained by the bounds of the image causes failure.

When the pixel data is ready the caller's ReadPixelsCallback is called with a AsyncReadResult containing pixel data in the requested color type, alpha type, and color space. The AsyncReadResult will have count() == 1. Upon failure the callback is called with nullptr for AsyncReadResult. For a GPU image this flushes work but a submit must occur to guarantee a finite time before the callback is called.

The data is valid for the lifetime of AsyncReadResult with the exception that if the SkImage is GPU-backed the data is immediately invalidated if the context is abandoned or destroyed.

Parameters

info	info of the requested pixels
srcRect	subrectangle of image to read
rescaleGamma	controls whether rescaling is done in the image's gamma or whether the source data is transformed to a linear gamma before rescaling.
rescaleMode	controls the technique (and cost) of the rescaling
callback	function to call with result of the read
context	passed to callback

◆ asyncRescaleAndReadPixelsYUV420()

void SkImage::asyncRescaleAndReadPixelsYUV420	(	SkYUVColorSpace	yuvColorSpace,
		sk_sp< SkColorSpace >	dstColorSpace,
		const SkIRect &	srcRect,
		const SkISize &	dstSize,
		RescaleGamma	rescaleGamma,
		RescaleMode	rescaleMode,
		ReadPixelsCallback	callback,
		ReadPixelsContext	context
	)		const

Similar to asyncRescaleAndReadPixels but performs an additional conversion to YUV.

The RGB->YUV conversion is controlled by 'yuvColorSpace'. The YUV data is returned as three planes ordered y, u, v. The u and v planes are half the width and height of the resized rectangle. The y, u, and v values are single bytes. Currently this fails if 'dstSize' width and height are not even. A 'srcRect' that is not contained by the bounds of the image causes failure.

When the pixel data is ready the caller's ReadPixelsCallback is called with a AsyncReadResult containing the planar data. The AsyncReadResult will have count() == 3. Upon failure the callback is called with nullptr for AsyncReadResult. For a GPU image this flushes work but a submit must occur to guarantee a finite time before the callback is called.

The data is valid for the lifetime of AsyncReadResult with the exception that if the SkImage is GPU-backed the data is immediately invalidated if the context is abandoned or destroyed.

Parameters

yuvColorSpace	The transformation from RGB to YUV. Applied to the resized image after it is converted to dstColorSpace.
dstColorSpace	The color space to convert the resized image to, after rescaling.
srcRect	The portion of the image to rescale and convert to YUV planes.
dstSize	The size to rescale srcRect to
rescaleGamma	controls whether rescaling is done in the image's gamma or whether the source data is transformed to a linear gamma before rescaling.
rescaleMode	controls the technique (and cost) of the rescaling
callback	function to call with the planar read result
context	passed to callback

◆ asyncRescaleAndReadPixelsYUVA420()

void SkImage::asyncRescaleAndReadPixelsYUVA420	(	SkYUVColorSpace	yuvColorSpace,
		sk_sp< SkColorSpace >	dstColorSpace,
		const SkIRect &	srcRect,
		const SkISize &	dstSize,
		RescaleGamma	rescaleGamma,
		RescaleMode	rescaleMode,
		ReadPixelsCallback	callback,
		ReadPixelsContext	context
	)		const

Identical to asyncRescaleAndReadPixelsYUV420 but a fourth plane is returned in the AsyncReadResult passed to 'callback'.

The fourth plane contains the alpha chanel at the same full resolution as the Y plane.

◆ bounds()

SkIRect SkImage::bounds ( ) const

inline

Returns SkIRect { 0, 0, width(), height() }.

Returns: integral rectangle from origin to width() and height()

◆ colorSpace()

SkColorSpace* SkImage::colorSpace ( ) const

Returns SkColorSpace, the range of colors, associated with SkImage.

The reference count of SkColorSpace is unchanged. The returned SkColorSpace is immutable.

SkColorSpace returned was passed to an SkImage constructor, or was parsed from encoded data. SkColorSpace returned may be ignored when SkImage is drawn, depending on the capabilities of the SkSurface receiving the drawing.

Returns: SkColorSpace in SkImage, or nullptr

example: https://fiddle.skia.org/c/@Image_colorSpace

◆ colorType()

SkColorType SkImage::colorType ( ) const

Returns SkColorType if known; otherwise, returns kUnknown_SkColorType.

Returns: SkColorType of SkImage

example: https://fiddle.skia.org/c/@Image_colorType

◆ dimensions()

SkISize SkImage::dimensions ( ) const

inline

Returns SkISize { width(), height() }.

Returns: integral size of width() and height()

◆ hasMipmaps()

bool SkImage::hasMipmaps ( ) const

Returns true if the image has mipmap levels.

◆ height()

int SkImage::height ( ) const

inline

Returns pixel row count.

Returns: pixel height in SkImage

◆ imageInfo()

const SkImageInfo& SkImage::imageInfo ( ) const

inline

Returns a SkImageInfo describing the width, height, color type, alpha type, and color space of the SkImage.

Returns: image info of SkImage.

◆ isAlphaOnly()

bool SkImage::isAlphaOnly ( ) const

Returns true if SkImage pixels represent transparency only.

If true, each pixel is packed in 8 bits as defined by kAlpha_8_SkColorType.

Returns: true if pixels represent a transparency mask

example: https://fiddle.skia.org/c/@Image_isAlphaOnly

◆ isLazyGenerated()

virtual bool SkImage::isLazyGenerated ( ) const

pure virtual

Returns true if SkImage is backed by an image-generator or other service that creates and caches its pixels or texture on-demand.

Returns: true if SkImage is created as needed

example: https://fiddle.skia.org/c/@Image_isLazyGenerated_a example: https://fiddle.skia.org/c/@Image_isLazyGenerated_b

◆ isOpaque()

bool SkImage::isOpaque ( ) const

inline

Returns true if pixels ignore their alpha value and are treated as fully opaque.

Returns: true if SkAlphaType is kOpaque_SkAlphaType

◆ isProtected()

bool SkImage::isProtected ( ) const

Returns true if the image holds protected content.

◆ isTextureBacked()

virtual bool SkImage::isTextureBacked ( ) const

pure virtual

Returns true if the contents of SkImage was created on or uploaded to GPU memory, and is available as a GPU texture.

Returns: true if SkImage is a GPU texture

example: https://fiddle.skia.org/c/@Image_isTextureBacked

◆ isValid()

virtual bool SkImage::isValid ( GrRecordingContext * context ) const

pure virtual

Returns true if SkImage can be drawn on either raster surface or GPU surface.

If context is nullptr, tests if SkImage draws on raster surface; otherwise, tests if SkImage draws on GPU surface associated with context.

SkImage backed by GPU texture may become invalid if associated context is invalid. lazy image may be invalid and may not draw to raster surface or GPU surface or both.

Parameters

context GPU context

Returns: true if SkImage can be drawn

example: https://fiddle.skia.org/c/@Image_isValid

◆ makeColorSpace() [1/2]

virtual sk_sp<SkImage> SkImage::makeColorSpace	(	GrDirectContext *	direct,
		sk_sp< SkColorSpace >	target
	)		const

pure virtual

Creates SkImage in target SkColorSpace.

Returns nullptr if SkImage could not be created.

Returns original SkImage if it is in target SkColorSpace. Otherwise, converts pixels from SkImage SkColorSpace to target SkColorSpace. If SkImage colorSpace() returns nullptr, SkImage SkColorSpace is assumed to be sRGB.

If this image is texture-backed, the context parameter is required and must match the context of the source image.

Parameters

direct	The GrDirectContext in play, if it exists
target	SkColorSpace describing color range of returned SkImage

Returns: created SkImage in target SkColorSpace

example: https://fiddle.skia.org/c/@Image_makeColorSpace

◆ makeColorSpace() [2/2]

virtual sk_sp<SkImage> SkImage::makeColorSpace	(	skgpu::graphite::Recorder *	,
		sk_sp< SkColorSpace >	targetColorSpace,
		RequiredProperties
	)		const

pure virtual

Creates SkImage in target SkColorSpace.

Returns nullptr if SkImage could not be created.

Returns original SkImage if it is in target SkColorSpace. Otherwise, converts pixels from SkImage SkColorSpace to target SkColorSpace. If SkImage colorSpace() returns nullptr, SkImage SkColorSpace is assumed to be sRGB.

If this image is graphite-backed, the recorder parameter is required.

Parameters

targetColorSpace	SkColorSpace describing color range of returned SkImage
recorder	The Recorder in which to create the new image
RequiredProperties	properties the returned SkImage must possess (e.g. mipmaps)

Returns: created SkImage in target SkColorSpace

◆ makeColorTypeAndColorSpace() [1/2]

virtual sk_sp<SkImage> SkImage::makeColorTypeAndColorSpace	(	GrDirectContext *	direct,
		SkColorType	targetColorType,
		sk_sp< SkColorSpace >	targetCS
	)		const

pure virtual

Experimental.

Creates SkImage in target SkColorType and SkColorSpace. Returns nullptr if SkImage could not be created.

Returns original SkImage if it is in target SkColorType and SkColorSpace.

If this image is texture-backed, the context parameter is required and must match the context of the source image.

Parameters

direct	The GrDirectContext in play, if it exists
targetColorType	SkColorType of returned SkImage
targetColorSpace	SkColorSpace of returned SkImage

Returns: created SkImage in target SkColorType and SkColorSpace

◆ makeColorTypeAndColorSpace() [2/2]

virtual sk_sp<SkImage> SkImage::makeColorTypeAndColorSpace	(	skgpu::graphite::Recorder *	,
		SkColorType	targetColorType,
		sk_sp< SkColorSpace >	targetColorSpace,
		RequiredProperties
	)		const

pure virtual

Experimental.

Creates SkImage in target SkColorType and SkColorSpace. Returns nullptr if SkImage could not be created.

Returns original SkImage if it is in target SkColorType and SkColorSpace.

If this image is graphite-backed, the recorder parameter is required.

Parameters

targetColorType	SkColorType of returned SkImage
targetColorSpace	SkColorSpace of returned SkImage
recorder	The Recorder in which to create the new image
RequiredProperties	properties the returned SkImage must possess (e.g. mipmaps)

Returns: created SkImage in target SkColorType and SkColorSpace

◆ makeNonTextureImage()

sk_sp<SkImage> SkImage::makeNonTextureImage ( GrDirectContext * = nullptr ) const

Returns raster image or lazy image.

Copies SkImage backed by GPU texture into CPU memory if needed. Returns original SkImage if decoded in raster bitmap, or if encoded in a stream.

Returns nullptr if backed by GPU texture and copy fails.

Returns: raster image, lazy image, or nullptr

example: https://fiddle.skia.org/c/@Image_makeNonTextureImage

◆ makeRasterImage() [1/2]

sk_sp<SkImage> SkImage::makeRasterImage ( CachingHint cachingHint = kDisallow_CachingHint ) const

inline

◆ makeRasterImage() [2/2]

sk_sp<SkImage> SkImage::makeRasterImage	(	GrDirectContext *	,
		CachingHint	cachingHint = `kDisallow_CachingHint`
	)		const

Returns raster image.

Copies SkImage backed by GPU texture into CPU memory, or decodes SkImage from lazy image. Returns original SkImage if decoded in raster bitmap.

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

If cachingHint is kAllow_CachingHint, pixels may be retained locally. If cachingHint is kDisallow_CachingHint, pixels are not added to the local cache.

Returns: raster image, or nullptr

example: https://fiddle.skia.org/c/@Image_makeRasterImage

◆ makeRawShader() [1/4]

sk_sp<SkShader> SkImage::makeRawShader	(	const SkSamplingOptions &	sampling,
		const SkMatrix &	lm
	)		const

Defaults to clamp in both X and Y.

◆ makeRawShader() [2/4]

sk_sp<SkShader> SkImage::makeRawShader	(	const SkSamplingOptions &	sampling,
		const SkMatrix *	lm = `nullptr`
	)		const

◆ makeRawShader() [3/4]

sk_sp<SkShader> SkImage::makeRawShader	(	SkTileMode	tmx,
		SkTileMode	tmy,
		const SkSamplingOptions &	,
		const SkMatrix *	localMatrix = `nullptr`
	)		const

makeRawShader functions like makeShader, but for images that contain non-color data.

This includes images encoding things like normals, material properties (eg, roughness), heightmaps, or any other purely mathematical data that happens to be stored in an image. These types of images are useful with some programmable shaders (see: SkRuntimeEffect).

Raw image shaders work like regular image shaders (including filtering and tiling), with a few major differences:

No color space transformation is ever applied (the color space of the image is ignored).
Images with an alpha type of kUnpremul are not automatically premultiplied.
Bicubic filtering is not supported. If SkSamplingOptions::useCubic is true, these factories will return nullptr.

◆ makeRawShader() [4/4]

sk_sp<SkShader> SkImage::makeRawShader	(	SkTileMode	tmx,
		SkTileMode	tmy,
		const SkSamplingOptions &	sampling,
		const SkMatrix &	lm
	)		const

◆ makeShader() [1/4]

sk_sp<SkShader> SkImage::makeShader	(	const SkSamplingOptions &	sampling,
		const SkMatrix &	lm
	)		const

Defaults to clamp in both X and Y.

◆ makeShader() [2/4]

sk_sp<SkShader> SkImage::makeShader	(	const SkSamplingOptions &	sampling,
		const SkMatrix *	lm = `nullptr`
	)		const

◆ makeShader() [3/4]

sk_sp<SkShader> SkImage::makeShader	(	SkTileMode	tmx,
		SkTileMode	tmy,
		const SkSamplingOptions &	,
		const SkMatrix *	localMatrix = `nullptr`
	)		const

Make a shader with the specified tiling and mipmap sampling.

◆ makeShader() [4/4]

sk_sp<SkShader> SkImage::makeShader	(	SkTileMode	tmx,
		SkTileMode	tmy,
		const SkSamplingOptions &	sampling,
		const SkMatrix &	lm
	)		const

◆ makeSubset() [1/2]

virtual sk_sp<SkImage> SkImage::makeSubset	(	GrDirectContext *	direct,
		const SkIRect &	subset
	)		const

pure virtual

Returns subset of this image.

Returns nullptr if any of the following are true:

Subset is empty
Subset is not contained inside the image's bounds
Pixels in the source image could not be read or copied
This image is texture-backed and the provided context is null or does not match the source image's context.

If the source image was texture-backed, the resulting image will be texture-backed also. Otherwise, the returned image will be raster-backed.

Parameters

direct	the GrDirectContext of the source image (nullptr is ok if the source image is not texture-backed).
subset	bounds of returned SkImage

Returns: the subsetted image, or nullptr

example: https://fiddle.skia.org/c/@Image_makeSubset

◆ makeSubset() [2/2]

virtual sk_sp<SkImage> SkImage::makeSubset	(	skgpu::graphite::Recorder *	,
		const SkIRect &	subset,
		RequiredProperties
	)		const

pure virtual

Returns subset of this image.

Returns nullptr if any of the following are true:

Subset is empty
Subset is not contained inside the image's bounds
Pixels in the image could not be read or copied
This image is texture-backed and the provided context is null or does not match the source image's context.

If the source image was texture-backed, the resulting image will be texture-backed also. Otherwise, the returned image will be raster-backed.

Parameters

recorder	the recorder of the source image (nullptr is ok if the source image was texture-backed).
subset	bounds of returned SkImage
RequiredProperties	properties the returned SkImage must possess (e.g. mipmaps)

Returns: the subsetted image, or nullptr

◆ peekPixels()

bool SkImage::peekPixels ( SkPixmap * pixmap ) const

Copies SkImage pixel address, row bytes, and SkImageInfo 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

Returns: true if SkImage has direct access to pixels

example: https://fiddle.skia.org/c/@Image_peekPixels

◆ readPixels() [1/4]

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

Deprecated.

Use the variants that accept a GrDirectContext.

◆ readPixels() [2/4]

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

◆ readPixels() [3/4]

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

Copies SkRect of pixels from SkImage to dstPixels.

Copy starts at offset (srcX, srcY), and does not exceed SkImage (width(), height()).

dstInfo specifies width, height, SkColorType, SkAlphaType, and SkColorSpace of destination. dstRowBytes specifies 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()
SkPixelRef is nullptr

Pixels are copied only if pixel conversion is possible. If SkImage SkColorType is kGray_8_SkColorType, or kAlpha_8_SkColorType; dstInfo.colorType() must match. If SkImage SkColorType is kGray_8_SkColorType, dstInfo.colorSpace() must match. If SkImage SkAlphaType is kOpaque_SkAlphaType, dstInfo.alphaType() must match. If SkImage SkColorSpace is nullptr, dstInfo.colorSpace() must match. Returns false if pixel conversion is not possible.

srcX and srcY may be negative to copy only top or left of source. Returns false if width() or height() is zero or negative. Returns false if abs(srcX) >= Image width(), or if abs(srcY) >= Image height().

If cachingHint is kAllow_CachingHint, pixels may be retained locally. If cachingHint is kDisallow_CachingHint, pixels are not added to the local cache.

Parameters

context	the GrDirectContext in play, if it exists
dstInfo	destination width, height, SkColorType, SkAlphaType, SkColorSpace
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	whether the pixels should be cached locally

Returns: true if pixels are copied to dstPixels

◆ readPixels() [4/4]

bool SkImage::readPixels	(	GrDirectContext *	context,
		const SkPixmap &	dst,
		int	srcX,
		int	srcY,
		CachingHint	cachingHint = `kAllow_CachingHint`
	)		const

Copies a SkRect of pixels from SkImage to dst.

Copy starts at (srcX, srcY), and does not exceed SkImage (width(), height()).

dst specifies width, height, SkColorType, SkAlphaType, SkColorSpace, 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
SkPixelRef is nullptr

Pixels are copied only if pixel conversion is possible. If SkImage SkColorType is kGray_8_SkColorType, or kAlpha_8_SkColorType; dst.colorType() must match. If SkImage SkColorType is kGray_8_SkColorType, dst.colorSpace() must match. If SkImage SkAlphaType is kOpaque_SkAlphaType, dst.alphaType() must match. If SkImage SkColorSpace is nullptr, dst.colorSpace() must match. Returns false if pixel conversion is not possible.

srcX and srcY may be negative to copy only top or left of source. Returns false if width() or height() is zero or negative. Returns false if abs(srcX) >= Image width(), or if abs(srcY) >= Image height().

If cachingHint is kAllow_CachingHint, pixels may be retained locally. If cachingHint is kDisallow_CachingHint, pixels are not added to the local cache.

Parameters

context	the GrDirectContext in play, if it exists
dst	destination SkPixmap: SkImageInfo, pixels, row bytes
srcX	column index whose absolute value is less than width()
srcY	row index whose absolute value is less than height()
cachingHint	whether the pixels should be cached locallyZ

Returns: true if pixels are copied to dst

◆ ref()

void SkRefCntBase::ref ( ) const

inlineinherited

Increment the reference count.

Must be balanced by a call to unref().

◆ refColorSpace()

sk_sp<SkColorSpace> SkImage::refColorSpace ( ) const

Returns a smart pointer to SkColorSpace, the range of colors, associated with SkImage.

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.

SkColorSpace returned was passed to an SkImage constructor, or was parsed from encoded data. SkColorSpace returned may be ignored when SkImage is drawn, depending on the capabilities of the SkSurface receiving the drawing.

Returns: SkColorSpace in SkImage, or nullptr, wrapped in a smart pointer

example: https://fiddle.skia.org/c/@Image_refColorSpace

◆ refEncodedData()

sk_sp<SkData> SkImage::refEncodedData ( ) const

Returns encoded SkImage pixels as SkData, if SkImage was created from supported encoded stream format.

Platform support for formats vary and may require building with one or more of: SK_ENCODE_JPEG, SK_ENCODE_PNG, SK_ENCODE_WEBP.

Returns nullptr if SkImage contents are not encoded.

Returns: encoded SkImage, or nullptr

example: https://fiddle.skia.org/c/@Image_refEncodedData

◆ reinterpretColorSpace()

sk_sp<SkImage> SkImage::reinterpretColorSpace ( sk_sp< SkColorSpace > newColorSpace ) const

Creates a new SkImage identical to this one, but with a different SkColorSpace.

This does not convert the underlying pixel data, so the resulting image will draw differently.

◆ scalePixels()

bool SkImage::scalePixels	(	const SkPixmap &	dst,
		const SkSamplingOptions &	,
		CachingHint	cachingHint = `kAllow_CachingHint`
	)		const

Copies SkImage 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 SkImage SkColorType is kGray_8_SkColorType, or kAlpha_8_SkColorType; dst.colorType() must match. If SkImage SkColorType is kGray_8_SkColorType, dst.colorSpace() must match. If SkImage SkAlphaType is kOpaque_SkAlphaType, dst.alphaType() must match. If SkImage SkColorSpace is nullptr, dst.colorSpace() must match. Returns false if pixel conversion is not possible.

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 SkPixmap: SkImageInfo, pixels, row bytes

Returns: true if pixels are scaled to fit dst

◆ textureSize()

virtual size_t SkImage::textureSize ( ) const

pure virtual

Returns an approximation of the amount of texture memory used by the image.

Returns zero if the image is not texture backed or if the texture has an external format.

◆ unique()

bool SkRefCntBase::unique ( ) const

inlineinherited

May return true if the caller is the only owner.

Ensures that all previous owner's actions are complete.

◆ uniqueID()

uint32_t SkImage::uniqueID ( ) const

inline

Returns value unique to image.

SkImage contents cannot change after SkImage is created. Any operation to create a new SkImage will receive generate a new unique number.

Returns: unique identifier

◆ unref()

void SkRefCntBase::unref ( ) const

inlineinherited

Decrement the reference count.

If the reference count is 1 before the decrement, then delete the object. Note that if this is the case, then the object needs to have been allocated via new, and not on the stack.

◆ width()

int SkImage::width ( ) const

inline

Returns pixel count in each row.

Returns: pixel width in SkImage

◆ withDefaultMipmaps()

sk_sp<SkImage> SkImage::withDefaultMipmaps ( ) const

Returns an image with the same "base" pixels as the this image, but with mipmap levels automatically generated and attached.

Friends And Related Function Documentation

◆ SkBitmap

friend class SkBitmap

friend

◆ SkImage_Base

friend class SkImage_Base

friend

◆ SkImage_Raster

friend class SkImage_Raster

friend

◆ SkMipmapBuilder

friend class SkMipmapBuilder

friend

The documentation for this class was generated from the following file:

/CHECKOUT/include/core/SkImage.h

Classes

Public Types

Public Member Functions

Friends

Detailed Description

Member Typedef Documentation

◆ ReadPixelsCallback

◆ ReadPixelsContext

Member Enumeration Documentation

◆ CachingHint

◆ LegacyBitmapMode

◆ RescaleGamma

◆ RescaleMode

Member Function Documentation

◆ alphaType()

◆ asLegacyBitmap()

◆ asyncRescaleAndReadPixels()

◆ asyncRescaleAndReadPixelsYUV420()

◆ asyncRescaleAndReadPixelsYUVA420()

◆ bounds()

◆ colorSpace()

◆ colorType()

◆ dimensions()

◆ hasMipmaps()

◆ height()

◆ imageInfo()

◆ isAlphaOnly()

◆ isLazyGenerated()

◆ isOpaque()

◆ isProtected()

◆ isTextureBacked()

◆ isValid()

◆ makeColorSpace() [1/2]

◆ makeColorSpace() [2/2]

◆ makeColorTypeAndColorSpace() [1/2]

◆ makeColorTypeAndColorSpace() [2/2]

◆ makeNonTextureImage()

◆ makeRasterImage() [1/2]

◆ makeRasterImage() [2/2]

◆ makeRawShader() [1/4]

◆ makeRawShader() [2/4]

◆ makeRawShader() [3/4]

◆ makeRawShader() [4/4]

◆ makeShader() [1/4]

◆ makeShader() [2/4]

◆ makeShader() [3/4]

◆ makeShader() [4/4]

◆ makeSubset() [1/2]

◆ makeSubset() [2/2]

◆ peekPixels()

◆ readPixels() [1/4]

◆ readPixels() [2/4]

◆ readPixels() [3/4]

◆ readPixels() [4/4]

◆ ref()

◆ refColorSpace()

◆ refEncodedData()

◆ reinterpretColorSpace()

◆ scalePixels()

◆ textureSize()

◆ unique()

◆ uniqueID()

◆ unref()

◆ width()

◆ withDefaultMipmaps()

Friends And Related Function Documentation

◆ SkBitmap

◆ SkImage_Base

◆ SkImage_Raster

◆ SkMipmapBuilder