SkImage Class Reference

#include <SkImage.h>

Inheritance diagram for SkImage:

Classes
class	AsyncReadResult
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 }
using	ReadPixelsContext = void *
using	ReadPixelsCallback = void(ReadPixelsContext, std::unique_ptr< const AsyncReadResult >)

Public Member Functions
const SkImageInfo &	imageInfo () const
int	width () const
int	height () const
SkISize	dimensions () const
SkIRect	bounds () const
uint32_t	uniqueID () const
SkAlphaType	alphaType () const
SkColorType	colorType () const
SkColorSpace *	colorSpace () const
sk_sp< SkColorSpace >	refColorSpace () const
bool	isAlphaOnly () const
bool	isOpaque () const
sk_sp< SkShader >	makeShader (SkTileMode tmx, SkTileMode tmy, const SkSamplingOptions &, const SkMatrix *localMatrix=nullptr) const
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
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
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
sk_sp< SkShader >	makeRawShader (const SkSamplingOptions &sampling, const SkMatrix *lm=nullptr) const
bool	peekPixels (SkPixmap *pixmap) const
virtual bool	isTextureBacked () const =0
virtual size_t	textureSize () const =0
virtual bool	isValid (GrRecordingContext *context) const =0
bool	readPixels (GrDirectContext *context, const SkImageInfo &dstInfo, void *dstPixels, size_t dstRowBytes, int srcX, int srcY, CachingHint cachingHint=kAllow_CachingHint) const
bool	readPixels (GrDirectContext *context, const SkPixmap &dst, int srcX, int srcY, CachingHint cachingHint=kAllow_CachingHint) const
bool	readPixels (const SkImageInfo &dstInfo, void *dstPixels, size_t dstRowBytes, int srcX, int srcY, CachingHint cachingHint=kAllow_CachingHint) const
bool	readPixels (const SkPixmap &dst, int srcX, int srcY, CachingHint cachingHint=kAllow_CachingHint) const
void	asyncRescaleAndReadPixels (const SkImageInfo &info, const SkIRect &srcRect, RescaleGamma rescaleGamma, RescaleMode rescaleMode, ReadPixelsCallback callback, ReadPixelsContext context) const
void	asyncRescaleAndReadPixelsYUV420 (SkYUVColorSpace yuvColorSpace, sk_sp< SkColorSpace > dstColorSpace, const SkIRect &srcRect, const SkISize &dstSize, RescaleGamma rescaleGamma, RescaleMode rescaleMode, ReadPixelsCallback callback, ReadPixelsContext context) const
void	asyncRescaleAndReadPixelsYUVA420 (SkYUVColorSpace yuvColorSpace, sk_sp< SkColorSpace > dstColorSpace, const SkIRect &srcRect, const SkISize &dstSize, RescaleGamma rescaleGamma, RescaleMode rescaleMode, ReadPixelsCallback callback, ReadPixelsContext context) const
bool	scalePixels (const SkPixmap &dst, const SkSamplingOptions &, CachingHint cachingHint=kAllow_CachingHint) const
sk_sp< SkData >	refEncodedData () const
virtual sk_sp< SkImage >	makeSubset (GrDirectContext *direct, const SkIRect &subset) const =0
virtual sk_sp< SkImage >	makeSubset (skgpu::graphite::Recorder *, const SkIRect &subset, RequiredProperties) const =0
bool	hasMipmaps () const
bool	isProtected () const
sk_sp< SkImage >	withDefaultMipmaps () const
sk_sp< SkImage >	makeNonTextureImage (GrDirectContext *=nullptr) const
sk_sp< SkImage >	makeRasterImage (GrDirectContext *, CachingHint cachingHint=kDisallow_CachingHint) const
sk_sp< SkImage >	makeRasterImage (CachingHint cachingHint=kDisallow_CachingHint) const
bool	asLegacyBitmap (SkBitmap *bitmap, LegacyBitmapMode legacyBitmapMode=kRO_LegacyBitmapMode) const
virtual bool	isLazyGenerated () const =0
virtual sk_sp< SkImage >	makeColorSpace (GrDirectContext *direct, sk_sp< SkColorSpace > target) const =0
virtual sk_sp< SkImage >	makeColorSpace (skgpu::graphite::Recorder *, sk_sp< SkColorSpace > targetColorSpace, RequiredProperties) const =0
virtual sk_sp< SkImage >	makeColorTypeAndColorSpace (GrDirectContext *direct, SkColorType targetColorType, sk_sp< SkColorSpace > targetCS) const =0
virtual sk_sp< SkImage >	makeColorTypeAndColorSpace (skgpu::graphite::Recorder *, SkColorType targetColorType, sk_sp< SkColorSpace > targetColorSpace, RequiredProperties) const =0
sk_sp< SkImage >	reinterpretColorSpace (sk_sp< SkColorSpace > newColorSpace) const
Public Member Functions inherited from SkRefCntBase
	SkRefCntBase ()
virtual	~SkRefCntBase ()
bool	unique () const
void	ref () const
void	unref () const

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.

Definition at line 272 of file SkImage.h.

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.

Definition at line 583 of file SkImage.h.

ReadPixelsContext

using SkImage::ReadPixelsContext = void*

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

Definition at line 578 of file SkImage.h.

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

Definition at line 463 of file SkImage.h.

                     {
        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

Definition at line 825 of file SkImage.h.

                          {
        kRO_LegacyBitmapMode, //!< returned bitmap is read-only and immutable
    };

RescaleGamma

enum class SkImage::RescaleGamma : bool

strong

Enumerator
kSrc
kLinear

Definition at line 585 of file SkImage.h.

: bool { kSrc, kLinear };

RescaleMode

enum class SkImage::RescaleMode

strong

Enumerator
kNearest
kLinear
kRepeatedLinear
kRepeatedCubic

Definition at line 587 of file SkImage.h.

                           {
        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

Definition at line 154 of file SkImage.cpp.

{ return fInfo.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

Definition at line 233 of file SkImage.cpp.

                                                                      {
    // Context TODO: Elevate GrDirectContext requirement to public API.
    auto dContext = as_IB(this)->directContext();
    return as_IB(this)->onAsLegacyBitmap(dContext, bitmap);
}

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

Definition at line 64 of file SkImage.cpp.

                                                                         {
    if (!SkIRect::MakeWH(this->width(), this->height()).contains(srcRect) ||
        !SkImageInfoIsValid(info)) {
        callback(context, nullptr);
        return;
    }
    as_IB(this)->onAsyncRescaleAndReadPixels(
            info, srcRect, rescaleGamma, rescaleMode, callback, context);
}

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

Definition at line 79 of file SkImage.cpp.

                                                                               {
    if (!SkIRect::MakeWH(this->width(), this->height()).contains(srcRect) || dstSize.isZero() ||
        (dstSize.width() & 0b1) || (dstSize.height() & 0b1)) {
        callback(context, nullptr);
        return;
    }
    as_IB(this)->onAsyncRescaleAndReadPixelsYUV420(yuvColorSpace,
                                                   /*readAlpha=*/false,
                                                   std::move(dstColorSpace),
                                                   srcRect,
                                                   dstSize,
                                                   rescaleGamma,
                                                   rescaleMode,
                                                   callback,
                                                   context);
}

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.

Definition at line 103 of file SkImage.cpp.

                                                                                {
    if (!SkIRect::MakeWH(this->width(), this->height()).contains(srcRect) || dstSize.isZero() ||
        (dstSize.width() & 0b1) || (dstSize.height() & 0b1)) {
        callback(context, nullptr);
        return;
    }
    as_IB(this)->onAsyncRescaleAndReadPixelsYUV420(yuvColorSpace,
                                                   /*readAlpha=*/true,
                                                   std::move(dstColorSpace),
                                                   srcRect,
                                                   dstSize,
                                                   rescaleGamma,
                                                   rescaleMode,
                                                   callback,
                                                   context);
}

bounds()

SkIRect SkImage::bounds ( ) const

inline

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

Returns

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

Definition at line 303 of file SkImage.h.

{ return SkIRect::MakeWH(fInfo.width(), fInfo.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

Definition at line 156 of file SkImage.cpp.

{ return fInfo.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

Definition at line 152 of file SkImage.cpp.

{ return fInfo.colorType(); }

dimensions()

SkISize SkImage::dimensions ( ) const

inline

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

Returns

integral size of width() and height()

Definition at line 297 of file SkImage.h.

{ return SkISize::Make(fInfo.width(), fInfo.height()); }

hasMipmaps()

bool SkImage::hasMipmaps

(

)

const

Returns true if the image has mipmap levels.

Definition at line 292 of file SkImage.cpp.

{ return as_IB(this)->onHasMipmaps(); }

height()

int SkImage::height ( ) const

inline

Returns pixel row count.

Returns

pixel height in SkImage

Definition at line 291 of file SkImage.h.

{ return fInfo.height(); }

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.

Definition at line 279 of file SkImage.h.

{ return fInfo; }

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

Definition at line 239 of file SkImage.cpp.

{ return SkColorTypeIsAlphaOnly(fInfo.colorType()); }

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

Implemented in SkImage_Base.

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

Definition at line 375 of file SkImage.h.

{ return SkAlphaTypeIsOpaque(this->alphaType()); }

isProtected()

bool SkImage::isProtected

(

)

const

Returns true if the image holds protected content.

Definition at line 294 of file SkImage.cpp.

{ return as_IB(this)->onIsProtected(); }

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

Implemented in SkImage_Base.

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

Implemented in SkImage_GaneshBase, skgpu::graphite::Image_Base, SkImage_Lazy, and SkImage_Raster.

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

Implemented in SkImage_Base.

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

Implemented in SkImage_Base.

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

Implemented in SkImage_GaneshBase, and SkImage_Base.

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

Implemented in skgpu::graphite::Image_Base, SkImage_GaneshBase, and SkImage_Base.

makeNonTextureImage()

sk_sp< SkImage > SkImage::makeNonTextureImage

(

GrDirectContext *

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

Definition at line 260 of file SkImage.cpp.

                                                                           {
    if (!this->isTextureBacked()) {
        return sk_ref_sp(const_cast<SkImage*>(this));
    }
    return this->makeRasterImage(dContext, kDisallow_CachingHint);
}

makeRasterImage() [1/2]

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

inline

Definition at line 818 of file SkImage.h.

                                                                                          {
        return this->makeRasterImage(nullptr, cachingHint);
    }

makeRasterImage() [2/2]

sk_sp< SkImage > SkImage::makeRasterImage	(	GrDirectContext *	dContext,
		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

Definition at line 267 of file SkImage.cpp.

                                                                                          {
    SkPixmap pm;
    if (this->peekPixels(&pm)) {
        return sk_ref_sp(const_cast<SkImage*>(this));
    }
 
    const size_t rowBytes = fInfo.minRowBytes();
    size_t size = fInfo.computeByteSize(rowBytes);
    if (SkImageInfo::ByteSizeOverflowed(size)) {
        return nullptr;
    }
 
    if (!dContext) {
        // Try to get the saved context if the client didn't pass it in (but they really should).
        dContext = as_IB(this)->directContext();
    }
    sk_sp<SkData> data = SkData::MakeUninitialized(size);
    pm = {fInfo.makeColorSpace(nullptr), data->writable_data(), fInfo.minRowBytes()};
    if (!this->readPixels(dContext, pm, 0, 0, chint)) {
        return nullptr;
    }
 
    return SkImages::RasterFromData(fInfo, std::move(data), rowBytes);
}

makeRawShader() [1/4]

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

Defaults to clamp in both X and Y.

Definition at line 193 of file SkImage.cpp.

                                                                 {
    return SkImageShader::MakeRaw(sk_ref_sp(const_cast<SkImage*>(this)),
                                  SkTileMode::kClamp, SkTileMode::kClamp,
                                  sampling, &lm);
}

makeRawShader() [2/4]

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

Definition at line 200 of file SkImage.cpp.

                                                                          {
    return SkImageShader::MakeRaw(sk_ref_sp(const_cast<SkImage*>(this)),
                                  SkTileMode::kClamp, SkTileMode::kClamp,
                                  sampling, localMatrix);
}

makeRawShader() [3/4]

sk_sp< SkShader > SkImage::makeRawShader	(	SkTileMode	tmx,
		SkTileMode	tmy,
		const SkSamplingOptions &	sampling,
		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.

Definition at line 207 of file SkImage.cpp.

                                                                          {
    return SkImageShader::MakeRaw(sk_ref_sp(const_cast<SkImage*>(this)), tmx, tmy,
                                  sampling, localMatrix);
}

makeRawShader() [4/4]

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

Definition at line 186 of file SkImage.cpp.

                                                                 {
    return SkImageShader::MakeRaw(sk_ref_sp(const_cast<SkImage*>(this)), tmx, tmy,
                                  sampling, &lm);
}

makeShader() [1/4]

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

Defaults to clamp in both X and Y.

Definition at line 160 of file SkImage.cpp.

                                                                                               {
    return SkImageShader::Make(sk_ref_sp(const_cast<SkImage*>(this)),
                               SkTileMode::kClamp, SkTileMode::kClamp,
                               sampling, &lm);
}

makeShader() [2/4]

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

Definition at line 166 of file SkImage.cpp.

                                                                                               {
    return SkImageShader::Make(sk_ref_sp(const_cast<SkImage*>(this)),
                               SkTileMode::kClamp, SkTileMode::kClamp,
                               sampling, lm);
}

makeShader() [3/4]

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

Make a shader with the specified tiling and mipmap sampling.

Definition at line 179 of file SkImage.cpp.

                                                                       {
    return SkImageShader::Make(sk_ref_sp(const_cast<SkImage*>(this)), tmx, tmy,
                               sampling, localMatrix);
}

makeShader() [4/4]

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

Definition at line 172 of file SkImage.cpp.

                                                              {
    return SkImageShader::Make(sk_ref_sp(const_cast<SkImage*>(this)), tmx, tmy,
                               sampling, &lm);
}

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

Implemented in SkImage_GaneshBase, and SkImage_Base.

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

Implemented in SkImage_Base.

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

Definition at line 34 of file SkImage.cpp.

                                           {
    SkPixmap tmp;
    if (!pm) {
        pm = &tmp;
    }
    return as_IB(this)->onPeekPixels(pm);
}

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.

Definition at line 48 of file SkImage.cpp.

                                                                                          {
    auto dContext = as_IB(this)->directContext();
    return this->readPixels(dContext, dstInfo, dstPixels, dstRowBytes, srcX, srcY, chint);
}

readPixels() [2/4]

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

Definition at line 227 of file SkImage.cpp.

                                                                                          {
    auto dContext = as_IB(this)->directContext();
    return this->readPixels(dContext, pmap, srcX, srcY, chint);
}

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

Definition at line 42 of file SkImage.cpp.

                                                                                          {
    return as_IB(this)->onReadPixels(dContext, dstInfo, dstPixels, dstRowBytes, srcX, srcY, chint);
}

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

Definition at line 220 of file SkImage.cpp.

                                                  {
    return this->readPixels(dContext, pmap.info(), pmap.writable_addr(), pmap.rowBytes(), srcX,
                            srcY, chint);
}

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

Definition at line 158 of file SkImage.cpp.

{ return fInfo.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

Definition at line 214 of file SkImage.cpp.

                                            {
    return sk_sp<SkData>(as_IB(this)->onRefEncoded());
}

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.

Definition at line 241 of file SkImage.cpp.

                                                                              {
    if (!target) {
        return nullptr;
    }
 
    // No need to create a new image if:
    // (1) The color spaces are equal.
    // (2) The color type is kAlpha8.
    SkColorSpace* colorSpace = this->colorSpace();
    if (!colorSpace) {
        colorSpace = sk_srgb_singleton();
    }
    if (SkColorSpace::Equals(colorSpace, target.get()) || this->isAlphaOnly()) {
        return sk_ref_sp(const_cast<SkImage*>(this));
    }
 
    return as_IB(this)->onReinterpretColorSpace(std::move(target));
}

scalePixels()

bool SkImage::scalePixels	(	const SkPixmap &	dst,
		const SkSamplingOptions &	sampling,
		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

Definition at line 127 of file SkImage.cpp.

                                                   {
    // Context TODO: Elevate GrDirectContext requirement to public API.
    auto dContext = as_IB(this)->directContext();
    if (this->width() == dst.width() && this->height() == dst.height()) {
        return this->readPixels(dContext, dst, 0, 0, chint);
    }
 
    // Idea: If/when SkImageGenerator supports a native-scaling API (where the generator itself
    //       can scale more efficiently) we should take advantage of it here.
    //
    SkBitmap bm;
    if (as_IB(this)->getROPixels(dContext, &bm, chint)) {
        SkPixmap pmap;
        // Note: By calling the pixmap scaler, we never cache the final result, so the chint
        //       is (currently) only being applied to the getROPixels. If we get a request to
        //       also attempt to cache the final (scaled) result, we would add that logic here.
        //
        return bm.peekPixels(&pmap) && pmap.scalePixels(dst, sampling);
    }
    return false;
}

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.

Implemented in SkImage_Ganesh, SkImage_GaneshYUVA, skgpu::graphite::Image, skgpu::graphite::Image_YUVA, and SkImage_Base.

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

Definition at line 311 of file SkImage.h.

{ return fUniqueID; }

width()

int SkImage::width ( ) const

inline

Returns pixel count in each row.

Returns

pixel width in SkImage

Definition at line 285 of file SkImage.h.

{ return fInfo.width(); }

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.

Definition at line 305 of file SkImage.cpp.

                                                 {
    return this->withMipmaps(nullptr);
}

Friends And Related Function Documentation

SkBitmap

friend class SkBitmap

friend

Definition at line 935 of file SkImage.h.

SkImage_Base

friend class SkImage_Base

friend

Definition at line 936 of file SkImage.h.

SkImage_Raster

friend class SkImage_Raster

friend

Definition at line 937 of file SkImage.h.

SkMipmapBuilder

friend class SkMipmapBuilder

friend

Definition at line 938 of file SkImage.h.

---

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

• third_party/skia/include/core/SkImage.h
• third_party/skia/src/image/SkImage.cpp