Skia
2D Graphics Library
SkImage Class Reference

#include <SkImage.h>

Inheritance diagram for SkImage:

Classes

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

Public Types

enum  CompressionType {
  CompressionType::kNone, CompressionType::kETC2_RGB8_UNORM, CompressionType::kBC1_RGB8_UNORM, CompressionType::kBC1_RGBA8_UNORM,
  CompressionType::kLast = kBC1_RGBA8_UNORM
}
 
enum  BitDepth { BitDepth::kU8, BitDepth::kF16 }
 
enum  CachingHint { kAllow_CachingHint, kDisallow_CachingHint }
 
enum  RescaleGamma : bool { RescaleGamma::kSrc, RescaleGamma::kLinear }
 
enum  LegacyBitmapMode { kRO_LegacyBitmapMode }
 Deprecated. More...
 
typedef void * ReleaseContext
 Caller data passed to RasterReleaseProc; may be nullptr. More...
 
typedef void(* RasterReleaseProc) (const void *pixels, ReleaseContext)
 Function called when SkImage no longer shares pixels. More...
 
typedef void(* TextureReleaseProc) (ReleaseContext releaseContext)
 User function called when supplied texture may be deleted. 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...
 
typedef std::function< void(GrBackendTexture)> BackendTextureReleaseProc
 Defines a callback function, taking one parameter of type GrBackendTexture with no return value. More...
 

Public Member Functions

const SkImageInfoimageInfo () 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...
 
SkColorSpacecolorSpace () const
 Returns SkColorSpace, the range of colors, associated with SkImage. More...
 
sk_sp< SkColorSpacerefColorSpace () 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< SkShadermakeShader (SkTileMode tmx, SkTileMode tmy, const SkFilterOptions &, const SkMatrix *localMatrix=nullptr) const
 Make a shader with the specified tiling and mipmap sampling. More...
 
sk_sp< SkShadermakeShader (SkTileMode tmx, SkTileMode tmy, CubicResampler, const SkMatrix *localMatrix=nullptr) const
 Make a shader with the specified tiling and CubicResampler parameters. More...
 
sk_sp< SkShadermakeShader (SkTileMode tmx, SkTileMode tmy, const SkMatrix *localMatrix=nullptr) const
 Creates SkShader from SkImage. More...
 
sk_sp< SkShadermakeShader (SkTileMode tmx, SkTileMode tmy, const SkMatrix &localMatrix) const
 
sk_sp< SkShadermakeShader (SkTileMode tmx, SkTileMode tmy, const SkMatrix *localMatrix, SkFilterQuality) const
 
sk_sp< SkShadermakeShader (const SkMatrix *localMatrix=nullptr) const
 Creates SkShader from SkImage. More...
 
sk_sp< SkShadermakeShader (const SkMatrix &localMatrix) const
 
bool peekPixels (SkPixmap *pixmap) const
 Copies SkImage pixel address, row bytes, and SkImageInfo to pixmap, if address is available, and returns true. More...
 
bool isTextureBacked () const
 Returns true the contents of SkImage was created on or uploaded to GPU memory, and is available as a GPU texture. More...
 
bool isValid (GrRecordingContext *context) const
 Returns true if SkImage can be drawn on either raster surface or GPU surface. More...
 
GrSemaphoresSubmitted flush (GrDirectContext *context, const GrFlushInfo &flushInfo)
 Flushes any pending uses of texture-backed images in the GPU backend. More...
 
void flush (GrDirectContext *context)
 
void flushAndSubmit (GrDirectContext *)
 Version of flush() that uses a default GrFlushInfo. More...
 
GrBackendTexture getBackendTexture (bool flushPendingGrContextIO, GrSurfaceOrigin *origin=nullptr) const
 Retrieves the back-end texture. 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, SkFilterQuality rescaleQuality, ReadPixelsCallback callback, ReadPixelsContext context)
 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, SkFilterQuality rescaleQuality, ReadPixelsCallback callback, ReadPixelsContext context)
 Similar to asyncRescaleAndReadPixels but performs an additional conversion to YUV. More...
 
bool scalePixels (const SkPixmap &dst, SkFilterQuality filterQuality, 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< SkDataencodeToData (SkEncodedImageFormat encodedImageFormat, int quality) const
 Encodes SkImage pixels, returning result as SkData. More...
 
sk_sp< SkDataencodeToData () const
 Encodes SkImage pixels, returning result as SkData. More...
 
sk_sp< SkDatarefEncodedData () const
 Returns encoded SkImage pixels as SkData, if SkImage was created from supported encoded stream format. More...
 
sk_sp< SkImagemakeSubset (const SkIRect &subset, GrDirectContext *direct=nullptr) const
 Returns subset of this image. More...
 
bool hasMipmaps () const
 Returns true if the image has mipmap levels. More...
 
sk_sp< SkImagewithDefaultMipmaps () const
 Returns an image with the same "base" pixels as the this image, but with mipmap levels automatically generated and attached. More...
 
sk_sp< SkImagemakeTextureImage (GrDirectContext *, GrMipmapped=GrMipmapped::kNo, SkBudgeted=SkBudgeted::kYes) const
 Returns SkImage backed by GPU texture associated with context. More...
 
sk_sp< SkImagemakeNonTextureImage () const
 Returns raster image or lazy image. More...
 
sk_sp< SkImagemakeRasterImage (CachingHint cachingHint=kDisallow_CachingHint) const
 Returns raster image. More...
 
sk_sp< SkImagemakeWithFilter (GrRecordingContext *context, const SkImageFilter *filter, const SkIRect &subset, const SkIRect &clipBounds, SkIRect *outSubset, SkIPoint *offset) const
 Creates filtered SkImage. More...
 
bool asLegacyBitmap (SkBitmap *bitmap, LegacyBitmapMode legacyBitmapMode=kRO_LegacyBitmapMode) const
 Deprecated. More...
 
bool isLazyGenerated () const
 Returns true if SkImage is backed by an image-generator or other service that creates and caches its pixels or texture on-demand. More...
 
sk_sp< SkImagemakeColorSpace (sk_sp< SkColorSpace > target, GrDirectContext *direct=nullptr) const
 Creates SkImage in target SkColorSpace. More...
 
sk_sp< SkImagemakeColorTypeAndColorSpace (SkColorType targetColorType, sk_sp< SkColorSpace > targetColorSpace, GrDirectContext *direct=nullptr) const
 Experimental. More...
 
sk_sp< SkImagereinterpretColorSpace (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...
 

Static Public Member Functions

static sk_sp< SkImageMakeRasterCopy (const SkPixmap &pixmap)
 Creates SkImage from SkPixmap and copy of pixels. More...
 
static sk_sp< SkImageMakeRasterData (const SkImageInfo &info, sk_sp< SkData > pixels, size_t rowBytes)
 Creates SkImage from SkImageInfo, sharing pixels. More...
 
static sk_sp< SkImageMakeFromRaster (const SkPixmap &pixmap, RasterReleaseProc rasterReleaseProc, ReleaseContext releaseContext)
 Creates SkImage from pixmap, sharing SkPixmap pixels. More...
 
static sk_sp< SkImageMakeFromBitmap (const SkBitmap &bitmap)
 Creates SkImage from bitmap, sharing or copying bitmap pixels. More...
 
static sk_sp< SkImageMakeFromGenerator (std::unique_ptr< SkImageGenerator > imageGenerator)
 Creates SkImage from data returned by imageGenerator. More...
 
static sk_sp< SkImageMakeFromEncoded (sk_sp< SkData > encoded)
 Return an image backed by the encoded data, but attempt to defer decoding until the image is actually used/drawn. More...
 
static sk_sp< SkImageMakeTextureFromCompressed (GrDirectContext *direct, sk_sp< SkData > data, int width, int height, CompressionType type, GrMipmapped mipMapped=GrMipmapped::kNo, GrProtected isProtected=GrProtected::kNo)
 Creates a GPU-backed SkImage from compressed data. More...
 
static sk_sp< SkImageMakeRasterFromCompressed (sk_sp< SkData > data, int width, int height, CompressionType type)
 Creates a CPU-backed SkImage from compressed data. More...
 
static sk_sp< SkImageMakeFromTexture (GrRecordingContext *context, const GrBackendTexture &backendTexture, GrSurfaceOrigin origin, SkColorType colorType, SkAlphaType alphaType, sk_sp< SkColorSpace > colorSpace, TextureReleaseProc textureReleaseProc=nullptr, ReleaseContext releaseContext=nullptr)
 Creates SkImage from GPU texture associated with context. More...
 
static sk_sp< SkImageMakeFromCompressedTexture (GrRecordingContext *context, const GrBackendTexture &backendTexture, GrSurfaceOrigin origin, SkAlphaType alphaType, sk_sp< SkColorSpace > colorSpace, TextureReleaseProc textureReleaseProc=nullptr, ReleaseContext releaseContext=nullptr)
 Creates an SkImage from a GPU backend texture. More...
 
static sk_sp< SkImageMakeCrossContextFromPixmap (GrDirectContext *context, const SkPixmap &pixmap, bool buildMips, bool limitToMaxTextureSize=false)
 Creates SkImage from pixmap. More...
 
static sk_sp< SkImageMakeFromAdoptedTexture (GrRecordingContext *context, const GrBackendTexture &backendTexture, GrSurfaceOrigin imageOrigin, SkColorType colorType, SkAlphaType alphaType=kPremul_SkAlphaType, sk_sp< SkColorSpace > colorSpace=nullptr)
 Creates SkImage from backendTexture associated with context. More...
 
static sk_sp< SkImageMakeFromYUVATexturesCopy (GrRecordingContext *context, SkYUVColorSpace yuvColorSpace, const GrBackendTexture yuvaTextures[], const SkYUVAIndex yuvaIndices[4], SkISize imageSize, GrSurfaceOrigin imageOrigin, sk_sp< SkColorSpace > imageColorSpace=nullptr)
 Creates an SkImage by flattening the specified YUVA planes into a single, interleaved RGBA image. More...
 
static sk_sp< SkImageMakeFromYUVATexturesCopyWithExternalBackend (GrRecordingContext *context, SkYUVColorSpace yuvColorSpace, const GrBackendTexture yuvaTextures[], const SkYUVAIndex yuvaIndices[4], SkISize imageSize, GrSurfaceOrigin imageOrigin, const GrBackendTexture &backendTexture, sk_sp< SkColorSpace > imageColorSpace=nullptr, TextureReleaseProc textureReleaseProc=nullptr, ReleaseContext releaseContext=nullptr)
 Creates an SkImage by flattening the specified YUVA planes into a single, interleaved RGBA image. More...
 
static sk_sp< SkImageMakeFromYUVATextures (GrContext *context, SkYUVColorSpace yuvColorSpace, const GrBackendTexture yuvaTextures[], const SkYUVAIndex yuvaIndices[4], SkISize imageSize, GrSurfaceOrigin imageOrigin, sk_sp< SkColorSpace > imageColorSpace=nullptr, TextureReleaseProc textureReleaseProc=nullptr, ReleaseContext releaseContext=nullptr)
 Creates an SkImage by storing the specified YUVA planes into an image, to be rendered via multitexturing. More...
 
static sk_sp< SkImageMakeFromYUVAPixmaps (GrRecordingContext *context, SkYUVColorSpace yuvColorSpace, const SkPixmap yuvaPixmaps[], const SkYUVAIndex yuvaIndices[4], SkISize imageSize, GrSurfaceOrigin imageOrigin, bool buildMips, bool limitToMaxTextureSize=false, sk_sp< SkColorSpace > imageColorSpace=nullptr)
 Creates SkImage from pixmap array representing YUVA data. More...
 
static sk_sp< SkImageMakeFromYUVAPixmaps (GrRecordingContext *context, const SkYUVAPixmaps &pixmaps, GrMipMapped buildMips=GrMipmapped::kNo, bool limitToMaxTextureSize=false, sk_sp< SkColorSpace > imageColorSpace=nullptr)
 Creates SkImage from SkYUVAPixmaps. More...
 
static sk_sp< SkImageMakeFromYUVTexturesCopyWithExternalBackend (GrContext *context, SkYUVColorSpace yuvColorSpace, const GrBackendTexture yuvTextures[3], GrSurfaceOrigin imageOrigin, const GrBackendTexture &backendTexture, sk_sp< SkColorSpace > imageColorSpace=nullptr)
 To be deprecated. More...
 
static sk_sp< SkImageMakeFromNV12TexturesCopy (GrContext *context, SkYUVColorSpace yuvColorSpace, const GrBackendTexture nv12Textures[2], GrSurfaceOrigin imageOrigin, sk_sp< SkColorSpace > imageColorSpace=nullptr)
 Creates SkImage from copy of nv12Textures, an array of textures on GPU. More...
 
static sk_sp< SkImageMakeFromNV12TexturesCopyWithExternalBackend (GrContext *context, SkYUVColorSpace yuvColorSpace, const GrBackendTexture nv12Textures[2], GrSurfaceOrigin imageOrigin, const GrBackendTexture &backendTexture, sk_sp< SkColorSpace > imageColorSpace=nullptr, TextureReleaseProc textureReleaseProc=nullptr, ReleaseContext releaseContext=nullptr)
 Creates SkImage from copy of nv12Textures, an array of textures on GPU. More...
 
static sk_sp< SkImageMakeFromPicture (sk_sp< SkPicture > picture, const SkISize &dimensions, const SkMatrix *matrix, const SkPaint *paint, BitDepth bitDepth, sk_sp< SkColorSpace > colorSpace)
 Creates SkImage from picture. More...
 
static bool MakeBackendTextureFromSkImage (GrContext *context, sk_sp< SkImage > image, GrBackendTexture *backendTexture, BackendTextureReleaseProc *backendTextureReleaseProc)
 Creates a GrBackendTexture from the provided SkImage. More...
 

Static Public Attributes

static constexpr int kCompressionTypeCount = static_cast<int>(CompressionType::kLast) + 1
 
static const CompressionType kETC1_CompressionType = CompressionType::kETC2_RGB8_UNORM
 

Friends

class SkImage_Base
 
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.

Member Typedef Documentation

◆ BackendTextureReleaseProc

Defines a callback function, taking one parameter of type GrBackendTexture with no return value.

Function is called when back-end texture is to be released.

◆ RasterReleaseProc

typedef void(* SkImage::RasterReleaseProc) (const void *pixels, ReleaseContext)

Function called when SkImage no longer shares pixels.

ReleaseContext is provided by caller when SkImage is created, and may be nullptr.

◆ 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

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

◆ ReleaseContext

typedef void* SkImage::ReleaseContext

Caller data passed to RasterReleaseProc; may be nullptr.

◆ TextureReleaseProc

typedef void(* SkImage::TextureReleaseProc) (ReleaseContext releaseContext)

User function called when supplied texture may be deleted.

Member Enumeration Documentation

◆ BitDepth

enum SkImage::BitDepth
strong
Enumerator
kU8 

uses 8-bit unsigned int per color component

kF16 

uses 16-bit float per color component

◆ CachingHint

Enumerator
kAllow_CachingHint 

allows internally caching decoded and copied pixels

kDisallow_CachingHint 

disallows internally caching decoded and copied pixels

◆ CompressionType

Enumerator
kNone 
kETC2_RGB8_UNORM 
kBC1_RGB8_UNORM 
kBC1_RGBA8_UNORM 
kLast 

◆ LegacyBitmapMode

Deprecated.

Enumerator
kRO_LegacyBitmapMode 

returned bitmap is read-only and immutable

◆ RescaleGamma

enum SkImage::RescaleGamma : bool
strong
Enumerator
kSrc 
kLinear 

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
bitmapstorage for legacy SkBitmap
legacyBitmapModebitmap is read-only and immutable
Returns
true if SkBitmap was created

◆ asyncRescaleAndReadPixels()

void SkImage::asyncRescaleAndReadPixels ( const SkImageInfo info,
const SkIRect srcRect,
RescaleGamma  rescaleGamma,
SkFilterQuality  rescaleQuality,
ReadPixelsCallback  callback,
ReadPixelsContext  context 
)

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 GrContext is abandoned or destroyed.

Parameters
infoinfo of the requested pixels
srcRectsubrectangle of image to read
rescaleGammacontrols whether rescaling is done in the image's gamma or whether the source data is transformed to a linear gamma before rescaling.
rescaleQualitycontrols the quality (and cost) of the rescaling
callbackfunction to call with result of the read
contextpassed to callback

◆ asyncRescaleAndReadPixelsYUV420()

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

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 GrContext is abandoned or destroyed.

Parameters
yuvColorSpaceThe transformation from RGB to YUV. Applied to the resized image after it is converted to dstColorSpace.
dstColorSpaceThe color space to convert the resized image to, after rescaling.
srcRectThe portion of the image to rescale and convert to YUV planes.
dstSizeThe size to rescale srcRect to
rescaleGammacontrols whether rescaling is done in the image's gamma or whether the source data is transformed to a linear gamma before rescaling.
rescaleQualitycontrols the quality (and cost) of the rescaling
callbackfunction to call with the planar read result
contextpassed to callback

◆ 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()

◆ encodeToData() [1/2]

sk_sp<SkData> SkImage::encodeToData ( ) const

Encodes SkImage pixels, returning result as SkData.

Returns existing encoded data if present; otherwise, SkImage is encoded with SkEncodedImageFormat::kPNG. Skia must be built with SK_ENCODE_PNG to encode SkImage.

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

Returns
encoded SkImage, or nullptr

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

◆ encodeToData() [2/2]

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

Encodes SkImage pixels, returning result as SkData.

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

SkImage encoding in a format requires both building with one or more of: SK_ENCODE_JPEG, SK_ENCODE_PNG, SK_ENCODE_WEBP; 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
encodedImageFormatone of: SkEncodedImageFormat::kJPEG, SkEncodedImageFormat::kPNG, SkEncodedImageFormat::kWEBP
qualityencoder specific metric with 100 equaling best
Returns
encoded SkImage, or nullptr

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

◆ flush() [1/2]

void SkImage::flush ( GrDirectContext context)
inline

◆ flush() [2/2]

GrSemaphoresSubmitted SkImage::flush ( GrDirectContext context,
const GrFlushInfo flushInfo 
)

Flushes any pending uses of texture-backed images in the GPU backend.

If the image is not texture-backed (including promise texture images) or if the GrDirectContext does not have the same context ID as the context backing the image then this is a no-op.

If the image was not used in any non-culled draws in the current queue of work for the passed GrDirectContext then this is a no-op unless the GrFlushInfo contains semaphores or a finish proc. Those are respected even when the image has not been used.

Parameters
contextthe context on which to flush pending usages of the image.
infoflush options

◆ flushAndSubmit()

void SkImage::flushAndSubmit ( GrDirectContext )

Version of flush() that uses a default GrFlushInfo.

Also submits the flushed work to the GPU.

◆ getBackendTexture()

GrBackendTexture SkImage::getBackendTexture ( bool  flushPendingGrContextIO,
GrSurfaceOrigin origin = nullptr 
) const

Retrieves the back-end texture.

If SkImage 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 SkImage.

Parameters
flushPendingGrContextIOflag to flush outstanding requests
Returns
back-end API texture handle; invalid on failure

◆ 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()

bool SkImage::isLazyGenerated ( ) const

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

◆ isTextureBacked()

bool SkImage::isTextureBacked ( ) const

Returns true 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()

bool SkImage::isValid ( GrRecordingContext context) const

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
contextGPU context
Returns
true if SkImage can be drawn

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

◆ MakeBackendTextureFromSkImage()

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

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 SkImage is both texture backed and singly referenced, image is returned in backendTexture without conversion or making a copy. SkImage is singly referenced if its was transferred solely using std::move().

If SkImage is not texture backed, returns texture with SkImage contents.

Parameters
contextGPU context
imageSkImage used for texture
backendTexturestorage for back-end texture
backendTextureReleaseProcstorage for clean up function
Returns
true if back-end texture was created

◆ makeColorSpace()

sk_sp<SkImage> SkImage::makeColorSpace ( sk_sp< SkColorSpace target,
GrDirectContext direct = nullptr 
) const

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
targetSkColorSpace describing color range of returned SkImage
directThe GrDirectContext in play, if it exists
Returns
created SkImage in target SkColorSpace

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

◆ makeColorTypeAndColorSpace()

sk_sp<SkImage> SkImage::makeColorTypeAndColorSpace ( SkColorType  targetColorType,
sk_sp< SkColorSpace targetColorSpace,
GrDirectContext direct = nullptr 
) const

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
targetColorTypeSkColorType of returned SkImage
targetColorSpaceSkColorSpace of returned SkImage
directThe GrDirectContext in play, if it exists
Returns
created SkImage in target SkColorType and SkColorSpace

◆ MakeCrossContextFromPixmap()

static sk_sp<SkImage> SkImage::MakeCrossContextFromPixmap ( GrDirectContext context,
const SkPixmap pixmap,
bool  buildMips,
bool  limitToMaxTextureSize = false 
)
static

Creates SkImage from pixmap.

SkImage is uploaded to GPU back-end using context.

Created SkImage 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 SkImage is no longer referenced, context releases texture memory asynchronously.

GrBackendTexture created from pixmap is uploaded to match SkSurface created with dstColorSpace. SkColorSpace of SkImage is determined by pixmap.colorSpace().

SkImage is returned referring to GPU back-end if context is not nullptr, format of data is recognized and supported, and if context supports moving resources between contexts. Otherwise, pixmap pixel data is copied and SkImage as returned in raster format if possible; nullptr may be returned. Recognized GPU formats vary by platform and GPU back-end.

Parameters
contextGPU context
pixmapSkImageInfo, pixel address, and row bytes
buildMipscreate SkImage as mip map if true
dstColorSpacerange of colors of matching SkSurface on GPU
limitToMaxTextureSizedownscale image to GPU maximum texture size, if necessary
Returns
created SkImage, or nullptr

◆ MakeFromAdoptedTexture()

static sk_sp<SkImage> SkImage::MakeFromAdoptedTexture ( GrRecordingContext context,
const GrBackendTexture backendTexture,
GrSurfaceOrigin  imageOrigin,
SkColorType  colorType,
SkAlphaType  alphaType = kPremul_SkAlphaType,
sk_sp< SkColorSpace colorSpace = nullptr 
)
static

Creates SkImage from backendTexture associated with context.

backendTexture and returned SkImage are managed internally, and are released when no longer needed.

SkImage is returned if format of backendTexture is recognized and supported. Recognized formats vary by GPU back-end.

Parameters
contextGPU context
backendTexturetexture residing on GPU
imageOriginorigin of the resulting image
colorTypecolor type of the resulting image
alphaTypealpha type of the resulting image
colorSpacerange of colors; may be nullptr
Returns
created SkImage, or nullptr

◆ MakeFromBitmap()

static sk_sp<SkImage> SkImage::MakeFromBitmap ( const SkBitmap bitmap)
static

Creates SkImage 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.

SkImage is returned if bitmap is valid. Valid SkBitmap parameters include: dimensions are greater than zero; each dimension fits in 29 bits; SkColorType and SkAlphaType are valid, and SkColorType is not kUnknown_SkColorType; row bytes are large enough to hold one row of pixels; pixel address is not nullptr.

Parameters
bitmapSkImageInfo, row bytes, and pixels
Returns
created SkImage, or nullptr

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

◆ MakeFromCompressedTexture()

static sk_sp<SkImage> SkImage::MakeFromCompressedTexture ( GrRecordingContext context,
const GrBackendTexture backendTexture,
GrSurfaceOrigin  origin,
SkAlphaType  alphaType,
sk_sp< SkColorSpace colorSpace,
TextureReleaseProc  textureReleaseProc = nullptr,
ReleaseContext  releaseContext = nullptr 
)
static

Creates an SkImage from a GPU backend texture.

The backend texture must stay valid and unchanged until textureReleaseProc is called. The textureReleaseProc is called when the SkImage is deleted or no longer refers to the texture and will be passed the releaseContext.

An SkImage is returned if the format of backendTexture is recognized and supported. Recognized formats vary by GPU back-end.

Note
When using a DDL recording context, textureReleaseProc will be called on the GPU thread after the DDL is played back on the direct context.
Parameters
contextthe GPU context
backendTexturea texture already allocated by the GPU
alphaTypeThis characterizes the nature of the alpha values in the backend texture. For opaque compressed formats (e.g., ETC1) this should usually be set to kOpaque_SkAlphaType.
colorSpaceThis describes the color space of this image's contents, as seen after sampling. In general, if the format of the backend texture is SRGB, some linear colorSpace should be supplied (e.g., SkColorSpace::MakeSRGBLinear()). If the format of the backend texture is linear, then the colorSpace should include a description of the transfer function as well (e.g., SkColorSpace::MakeSRGB()).
textureReleaseProcfunction called when the backend texture can be released
releaseContextstate passed to textureReleaseProc
Returns
created SkImage, or nullptr

◆ MakeFromEncoded()

static sk_sp<SkImage> SkImage::MakeFromEncoded ( sk_sp< SkData encoded)
static

Return an image backed by the encoded data, but attempt to defer decoding until the image is actually used/drawn.

This deferral allows the system to cache the result, either on the CPU or on the GPU, depending on where the image is drawn. If memory is low, the cache may be purged, causing the next draw of the image to have to re-decode.

The subset parameter specifies a area within the decoded image to create the image from. If subset is null, then the entire image is returned.

This is similar to DecodeTo[Raster,Texture], but this method will attempt to defer the actual decode, while the DecodeTo... method explicitly decode and allocate the backend when the call is made.

If the encoded format is not supported, or subset is outside of the bounds of the decoded image, nullptr is returned.

Parameters
encodedthe encoded data
lengththe number of bytes of encoded data
Returns
created SkImage, or nullptr

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

◆ MakeFromGenerator()

static sk_sp<SkImage> SkImage::MakeFromGenerator ( std::unique_ptr< SkImageGenerator imageGenerator)
static

Creates SkImage from data returned by imageGenerator.

Generated data is owned by SkImage and may not be shared or accessed.

SkImage is returned if generator data is valid. Valid data parameters vary by type of data and platform.

imageGenerator may wrap SkPicture data, codec data, or custom data.

Parameters
imageGeneratorstock or custom routines to retrieve SkImage
Returns
created SkImage, or nullptr

◆ MakeFromNV12TexturesCopy()

static sk_sp<SkImage> SkImage::MakeFromNV12TexturesCopy ( GrContext context,
SkYUVColorSpace  yuvColorSpace,
const GrBackendTexture  nv12Textures[2],
GrSurfaceOrigin  imageOrigin,
sk_sp< SkColorSpace imageColorSpace = nullptr 
)
static

Creates SkImage from copy of nv12Textures, an array of textures on GPU.

nv12Textures[0] contains pixels for YUV component y plane. nv12Textures[1] contains pixels for YUV component u plane, followed by pixels for YUV component v plane. Returned SkImage has the dimensions nv12Textures[2]. yuvColorSpace describes how YUV colors convert to RGB colors.

Parameters
contextGPU context
yuvColorSpaceHow the YUV values are converted to RGB
nv12Texturesarray of YUV textures on GPU
imageColorSpacerange of colors; may be nullptr
Returns
created SkImage, or nullptr

◆ MakeFromNV12TexturesCopyWithExternalBackend()

static sk_sp<SkImage> SkImage::MakeFromNV12TexturesCopyWithExternalBackend ( GrContext context,
SkYUVColorSpace  yuvColorSpace,
const GrBackendTexture  nv12Textures[2],
GrSurfaceOrigin  imageOrigin,
const GrBackendTexture backendTexture,
sk_sp< SkColorSpace imageColorSpace = nullptr,
TextureReleaseProc  textureReleaseProc = nullptr,
ReleaseContext  releaseContext = nullptr 
)
static

Creates SkImage from copy of nv12Textures, an array of textures on GPU.

nv12Textures[0] contains pixels for YUV component y plane. nv12Textures[1] contains pixels for YUV component u plane, followed by pixels for YUV component v plane. Returned SkImage has the dimensions nv12Textures[2] and stores pixels in backendTexture. yuvColorSpace describes how YUV colors convert to RGB colors.

Parameters
contextGPU context
yuvColorSpaceHow the YUV values are converted to RGB
nv12Texturesarray of YUV textures on GPU
backendTexturethe resource that stores the final pixels
imageColorSpacerange of colors; may be nullptr
textureReleaseProcfunction called when backendTexture can be released
releaseContextstate passed to textureReleaseProc
Returns
created SkImage, or nullptr

◆ MakeFromPicture()

static sk_sp<SkImage> SkImage::MakeFromPicture ( sk_sp< SkPicture picture,
const SkISize dimensions,
const SkMatrix matrix,
const SkPaint paint,
BitDepth  bitDepth,
sk_sp< SkColorSpace colorSpace 
)
static

Creates SkImage from picture.

Returned SkImage width and height are set by dimensions. SkImage draws picture with matrix and paint, set to bitDepth and colorSpace.

If matrix is nullptr, draws with identity SkMatrix. If paint is nullptr, draws with default SkPaint. colorSpace may be nullptr.

Parameters
picturestream of drawing commands
dimensionswidth and height
matrixSkMatrix to rotate, scale, translate, and so on; may be nullptr
paintSkPaint to apply transparency, filtering, and so on; may be nullptr
bitDepth8-bit integer or 16-bit float: per component
colorSpacerange of colors; may be nullptr
Returns
created SkImage, or nullptr

◆ MakeFromRaster()

static sk_sp<SkImage> SkImage::MakeFromRaster ( const SkPixmap pixmap,
RasterReleaseProc  rasterReleaseProc,
ReleaseContext  releaseContext 
)
static

Creates SkImage from pixmap, sharing SkPixmap pixels.

Pixels must remain valid and unchanged until rasterReleaseProc is called. rasterReleaseProc is passed releaseContext when SkImage is deleted or no longer refers to pixmap pixels.

Pass nullptr for rasterReleaseProc to share SkPixmap without requiring a callback when SkImage is released. Pass nullptr for releaseContext if rasterReleaseProc does not require state.

SkImage is returned if pixmap is valid. Valid SkPixmap parameters include: dimensions are greater than zero; each dimension fits in 29 bits; SkColorType and SkAlphaType are valid, and SkColorType is not kUnknown_SkColorType; row bytes are large enough to hold one row of pixels; pixel address is not nullptr.

Parameters
pixmapSkImageInfo, pixel address, and row bytes
rasterReleaseProcfunction called when pixels can be released; or nullptr
releaseContextstate passed to rasterReleaseProc; or nullptr
Returns
SkImage sharing pixmap

◆ MakeFromTexture()

static sk_sp<SkImage> SkImage::MakeFromTexture ( GrRecordingContext context,
const GrBackendTexture backendTexture,
GrSurfaceOrigin  origin,
SkColorType  colorType,
SkAlphaType  alphaType,
sk_sp< SkColorSpace colorSpace,
TextureReleaseProc  textureReleaseProc = nullptr,
ReleaseContext  releaseContext = nullptr 
)
static

Creates SkImage from GPU texture associated with context.

GPU texture must stay valid and unchanged until textureReleaseProc is called. textureReleaseProc is passed releaseContext when SkImage is deleted or no longer refers to texture.

SkImage is returned if format of backendTexture is recognized and supported. Recognized formats vary by GPU back-end.

Note
When using a DDL recording context, textureReleaseProc will be called on the GPU thread after the DDL is played back on the direct context.
Parameters
contextGPU context
backendTexturetexture residing on GPU
colorSpaceThis describes the color space of this image's contents, as seen after sampling. In general, if the format of the backend texture is SRGB, some linear colorSpace should be supplied (e.g., SkColorSpace::MakeSRGBLinear()). If the format of the backend texture is linear, then the colorSpace should include a description of the transfer function as well (e.g., SkColorSpace::MakeSRGB()).
textureReleaseProcfunction called when texture can be released
releaseContextstate passed to textureReleaseProc
Returns
created SkImage, or nullptr

◆ MakeFromYUVAPixmaps() [1/2]

static sk_sp<SkImage> SkImage::MakeFromYUVAPixmaps ( GrRecordingContext context,
const SkYUVAPixmaps pixmaps,
GrMipMapped  buildMips = GrMipmapped::kNo,
bool  limitToMaxTextureSize = false,
sk_sp< SkColorSpace imageColorSpace = nullptr 
)
static

Creates SkImage from SkYUVAPixmaps.

The image will remain planar with each plane converted to a texture using the passed GrRecordingContext.

SkYUVAPixmaps has a SkYUVAInfo which specifies the transformation from YUV to RGB. The SkColorSpace of the resulting RGB values is specified by imageColorSpace. This will be the SkColorSpace reported by the image and when drawn the RGB values will be converted from this space into the destination space (if the destination is tagged).

Currently, this is only supported using the GPU backend and will fail if context is nullptr.

SkYUVAPixmaps does not need to remain valid after this returns.

Parameters
contextGPU context
pixmapsThe planes as pixmaps with supported SkYUVAInfo that specifies conversion to RGB.
buildMipscreate internal YUVA textures as mip map if kYes. This is silently ignored if the context does not support mip maps.
limitToMaxTextureSizedownscale image to GPU maximum texture size, if necessary
imageColorSpacerange of colors of the resulting image; may be nullptr
Returns
created SkImage, or nullptr

◆ MakeFromYUVAPixmaps() [2/2]

static sk_sp<SkImage> SkImage::MakeFromYUVAPixmaps ( GrRecordingContext context,
SkYUVColorSpace  yuvColorSpace,
const SkPixmap  yuvaPixmaps[],
const SkYUVAIndex  yuvaIndices[4],
SkISize  imageSize,
GrSurfaceOrigin  imageOrigin,
bool  buildMips,
bool  limitToMaxTextureSize = false,
sk_sp< SkColorSpace imageColorSpace = nullptr 
)
static

Creates SkImage from pixmap array representing YUVA data.

SkImage is uploaded to GPU back-end using context.

Each GrBackendTexture created from yuvaPixmaps array is uploaded to match SkSurface using SkColorSpace of SkPixmap. SkColorSpace of SkImage is determined by imageColorSpace.

SkImage is returned referring to GPU back-end if context is not nullptr and format of data is recognized and supported. Otherwise, nullptr is returned. Recognized GPU formats vary by platform and GPU back-end.

Parameters
contextGPU context
yuvColorSpaceHow the YUV values are converted to RGB
yuvaPixmapsarray of (up to four) SkPixmap which contain the, possibly interleaved, YUVA planes
yuvaIndicesarray indicating which pixmap in yuvaPixmaps, and channel in that pixmap, maps to each component of YUVA.
imageSizesize of the resulting image
imageOriginorigin of the resulting image.
buildMipscreate internal YUVA textures as mip map if true
limitToMaxTextureSizedownscale image to GPU maximum texture size, if necessary
imageColorSpacerange of colors of the resulting image; may be nullptr
Returns
created SkImage, or nullptr

◆ MakeFromYUVATextures()

static sk_sp<SkImage> SkImage::MakeFromYUVATextures ( GrContext context,
SkYUVColorSpace  yuvColorSpace,
const GrBackendTexture  yuvaTextures[],
const SkYUVAIndex  yuvaIndices[4],
SkISize  imageSize,
GrSurfaceOrigin  imageOrigin,
sk_sp< SkColorSpace imageColorSpace = nullptr,
TextureReleaseProc  textureReleaseProc = nullptr,
ReleaseContext  releaseContext = nullptr 
)
static

Creates an SkImage by storing the specified YUVA planes into an image, to be rendered via multitexturing.

When all the provided backend textures can be released 'textureReleaseProc' will be called with 'releaseContext'. It will be called even if this method fails.

Parameters
contextGPU context
yuvColorSpaceHow the YUV values are converted to RGB
yuvaTexturesarray of (up to four) YUVA textures on GPU which contain the, possibly interleaved, YUVA planes
yuvaIndicesarray indicating which texture in yuvaTextures, and channel in that texture, maps to each component of YUVA.
imageSizesize of the resulting image
imageOriginorigin of the resulting image.
imageColorSpacerange of colors of the resulting image; may be nullptr
textureReleaseProccalled when the backend textures can be released
releaseContextstate passed to textureReleaseProc
Returns
created SkImage, or nullptr

◆ MakeFromYUVATexturesCopy()

static sk_sp<SkImage> SkImage::MakeFromYUVATexturesCopy ( GrRecordingContext context,
SkYUVColorSpace  yuvColorSpace,
const GrBackendTexture  yuvaTextures[],
const SkYUVAIndex  yuvaIndices[4],
SkISize  imageSize,
GrSurfaceOrigin  imageOrigin,
sk_sp< SkColorSpace imageColorSpace = nullptr 
)
static

Creates an SkImage by flattening the specified YUVA planes into a single, interleaved RGBA image.

Parameters
contextGPU context
yuvColorSpaceHow the YUV values are converted to RGB
yuvaTexturesarray of (up to four) YUVA textures on GPU which contain the, possibly interleaved, YUVA planes
yuvaIndicesarray indicating which texture in yuvaTextures, and channel in that texture, maps to each component of YUVA.
imageSizesize of the resulting image
imageOriginorigin of the resulting image.
imageColorSpacerange of colors of the resulting image; may be nullptr
Returns
created SkImage, or nullptr

◆ MakeFromYUVATexturesCopyWithExternalBackend()

static sk_sp<SkImage> SkImage::MakeFromYUVATexturesCopyWithExternalBackend ( GrRecordingContext context,
SkYUVColorSpace  yuvColorSpace,
const GrBackendTexture  yuvaTextures[],
const SkYUVAIndex  yuvaIndices[4],
SkISize  imageSize,
GrSurfaceOrigin  imageOrigin,
const GrBackendTexture backendTexture,
sk_sp< SkColorSpace imageColorSpace = nullptr,
TextureReleaseProc  textureReleaseProc = nullptr,
ReleaseContext  releaseContext = nullptr 
)
static

Creates an SkImage by flattening the specified YUVA planes into a single, interleaved RGBA image.

'backendTexture' is used to store the result of the flattening.

Parameters
contextGPU context
yuvColorSpaceHow the YUV values are converted to RGB
yuvaTexturesarray of (up to four) YUVA textures on GPU which contain the, possibly interleaved, YUVA planes
yuvaIndicesarray indicating which texture in yuvaTextures, and channel in that texture, maps to each component of YUVA.
imageSizesize of the resulting image
imageOriginorigin of the resulting image.
backendTexturethe resource that stores the final pixels
imageColorSpacerange of colors of the resulting image; may be nullptr
textureReleaseProcfunction called when backendTexture can be released
releaseContextstate passed to textureReleaseProc
Returns
created SkImage, or nullptr

◆ MakeFromYUVTexturesCopyWithExternalBackend()

static sk_sp<SkImage> SkImage::MakeFromYUVTexturesCopyWithExternalBackend ( GrContext context,
SkYUVColorSpace  yuvColorSpace,
const GrBackendTexture  yuvTextures[3],
GrSurfaceOrigin  imageOrigin,
const GrBackendTexture backendTexture,
sk_sp< SkColorSpace imageColorSpace = nullptr 
)
static

To be deprecated.

◆ makeNonTextureImage()

sk_sp<SkImage> SkImage::makeNonTextureImage ( ) 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

◆ MakeRasterCopy()

static sk_sp<SkImage> SkImage::MakeRasterCopy ( const SkPixmap pixmap)
static

Creates SkImage from SkPixmap and copy of pixels.

Since pixels are copied, SkPixmap pixels may be modified or deleted without affecting SkImage.

SkImage is returned if SkPixmap is valid. Valid SkPixmap parameters include: dimensions are greater than zero; each dimension fits in 29 bits; SkColorType and SkAlphaType are valid, and SkColorType is not kUnknown_SkColorType; row bytes are large enough to hold one row of pixels; pixel address is not nullptr.

Parameters
pixmapSkImageInfo, pixel address, and row bytes
Returns
copy of SkPixmap pixels, or nullptr

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

◆ MakeRasterData()

static sk_sp<SkImage> SkImage::MakeRasterData ( const SkImageInfo info,
sk_sp< SkData pixels,
size_t  rowBytes 
)
static

Creates SkImage from SkImageInfo, sharing pixels.

SkImage is returned if SkImageInfo is valid. Valid SkImageInfo parameters include: dimensions are greater than zero; each dimension fits in 29 bits; SkColorType and SkAlphaType are valid, and SkColorType is not kUnknown_SkColorType; rowBytes are large enough to hold one row of pixels; pixels is not nullptr, and contains enough data for SkImage.

Parameters
infocontains width, height, SkAlphaType, SkColorType, SkColorSpace
pixelsaddress or pixel storage
rowBytessize of pixel row or larger
Returns
SkImage sharing pixels, or nullptr

◆ MakeRasterFromCompressed()

static sk_sp<SkImage> SkImage::MakeRasterFromCompressed ( sk_sp< SkData data,
int  width,
int  height,
CompressionType  type 
)
static

Creates a CPU-backed SkImage from compressed data.

This method will decompress the compressed data and create an image wrapping it. Any mipmap levels present in the compressed data are discarded.

Parameters
datacompressed data to store in SkImage
widthwidth of full SkImage
heightheight of full SkImage
typetype of compression used
Returns
created SkImage, or nullptr

◆ makeRasterImage()

sk_sp<SkImage> SkImage::makeRasterImage ( 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

◆ makeShader() [1/7]

sk_sp<SkShader> SkImage::makeShader ( const SkMatrix localMatrix) const
inline

◆ makeShader() [2/7]

sk_sp<SkShader> SkImage::makeShader ( const SkMatrix localMatrix = nullptr) const
inline

Creates SkShader from SkImage.

SkShader dimensions are taken from SkImage. SkShader uses SkShader::kClamp_TileMode to fill drawn area outside SkImage. localMatrix permits transforming SkImage before SkCanvas matrix is applied.

Parameters
localMatrixSkImage transformation, or nullptr
Returns
SkShader containing SkImage

◆ makeShader() [3/7]

sk_sp<SkShader> SkImage::makeShader ( SkTileMode  tmx,
SkTileMode  tmy,
const SkFilterOptions ,
const SkMatrix localMatrix = nullptr 
) const

Make a shader with the specified tiling and mipmap sampling.

◆ makeShader() [4/7]

sk_sp<SkShader> SkImage::makeShader ( SkTileMode  tmx,
SkTileMode  tmy,
const SkMatrix localMatrix 
) const
inline

◆ makeShader() [5/7]

sk_sp<SkShader> SkImage::makeShader ( SkTileMode  tmx,
SkTileMode  tmy,
const SkMatrix localMatrix,
SkFilterQuality   
) const

◆ makeShader() [6/7]

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

Creates SkShader from SkImage.

SkShader dimensions are taken from SkImage. SkShader uses SkTileMode rules to fill drawn area outside SkImage. localMatrix permits transforming SkImage before SkCanvas matrix is applied.

Note: since no filter-quality is specified, it will be determined at draw time using the paint.

Parameters
tmxtiling in the x direction
tmytiling in the y direction
localMatrixSkImage transformation, or nullptr
Returns
SkShader containing SkImage

◆ makeShader() [7/7]

sk_sp<SkShader> SkImage::makeShader ( SkTileMode  tmx,
SkTileMode  tmy,
CubicResampler  ,
const SkMatrix localMatrix = nullptr 
) const

Make a shader with the specified tiling and CubicResampler parameters.

Returns nullptr if the resampler values are outside of [0...1]

◆ makeSubset()

sk_sp<SkImage> SkImage::makeSubset ( const SkIRect subset,
GrDirectContext direct = nullptr 
) const

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

If this image is texture-backed, the context parameter is required and must match the context of the source image. If the context parameter is provided, and the image is raster-backed, the subset will be converted to texture-backed.

Parameters
subsetbounds of returned SkImage
contextthe GrDirectContext in play, if it exists
Returns
the subsetted image, or nullptr

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

◆ MakeTextureFromCompressed()

static sk_sp<SkImage> SkImage::MakeTextureFromCompressed ( GrDirectContext direct,
sk_sp< SkData data,
int  width,
int  height,
CompressionType  type,
GrMipmapped  mipMapped = GrMipmapped::kNo,
GrProtected  isProtected = GrProtected::kNo 
)
static

Creates a GPU-backed SkImage from compressed data.

This method will return an SkImage representing the compressed data. If the GPU doesn't support the specified compression method, the data will be decompressed and then wrapped in a GPU-backed image.

Note: one can query the supported compression formats via GrContext::compressedBackendFormat.

Parameters
contextGPU context
datacompressed data to store in SkImage
widthwidth of full SkImage
heightheight of full SkImage
typetype of compression used
mipMappeddoes 'data' contain data for all the mipmap levels?
isProtecteddo the contents of 'data' require DRM protection (on Vulkan)?
Returns
created SkImage, or nullptr

◆ makeTextureImage()

sk_sp<SkImage> SkImage::makeTextureImage ( GrDirectContext ,
GrMipmapped  = GrMipmapped::kNo,
SkBudgeted  = SkBudgeted::kYes 
) const

Returns SkImage backed by GPU texture associated with context.

Returned SkImage is compatible with SkSurface created with dstColorSpace. The returned SkImage respects mipMapped setting; if mipMapped equals GrMipmapped::kYes, the backing texture allocates mip map levels.

The mipMapped parameter is effectively treated as kNo if MIP maps are not supported by the GPU.

Returns original SkImage if the image is already texture-backed, the context matches, and mipMapped is compatible with the backing GPU texture. SkBudgeted is ignored in this case.

Returns nullptr if context is nullptr, or if SkImage was created with another GrDirectContext.

Parameters
GrDirectContextthe GrDirectContext in play, if it exists
GrMipmappedwhether created SkImage texture must allocate mip map levels
SkBudgetedwhether to count a newly created texture for the returned image counts against the GrContext's budget.
Returns
created SkImage, or nullptr

◆ makeWithFilter()

sk_sp<SkImage> SkImage::makeWithFilter ( GrRecordingContext context,
const SkImageFilter filter,
const SkIRect subset,
const SkIRect clipBounds,
SkIRect outSubset,
SkIPoint offset 
) const

Creates filtered SkImage.

filter processes original SkImage, potentially changing color, position, and size. subset is the bounds of original SkImage processed by filter. clipBounds is the expected bounds of the filtered SkImage. outSubset is required storage for the actual bounds of the filtered SkImage. offset is required storage for translation of returned SkImage.

Returns nullptr if SkImage could not be created or if the recording context provided doesn't match the GPU context in which the image was created. If nullptr is returned, outSubset and offset are undefined.

Useful for animation of SkImageFilter that varies size from frame to frame. Returned SkImage 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 SkImage to keep subsequent animation frames aligned with respect to each other.

Parameters
contextthe GrRecordingContext in play - if it exists
filterhow SkImage is sampled when transformed
subsetbounds of SkImage processed by filter
clipBoundsexpected bounds of filtered SkImage
outSubsetstorage for returned SkImage bounds
offsetstorage for returned SkImage translation
Returns
filtered SkImage, 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
pixmapstorage 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
contextthe GrDirectContext in play, if it exists
dstInfodestination width, height, SkColorType, SkAlphaType, SkColorSpace
dstPixelsdestination pixel storage
dstRowBytesdestination row length
srcXcolumn index whose absolute value is less than width()
srcYrow index whose absolute value is less than height()
cachingHintwhether 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:

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
contextthe GrDirectContext in play, if it exists
dstdestination SkPixmap: SkImageInfo, pixels, row bytes
srcXcolumn index whose absolute value is less than width()
srcYrow index whose absolute value is less than height()
cachingHintwhether 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,
SkFilterQuality  filterQuality,
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.

Scales the image, with filterQuality, to match dst.width() and dst.height(). filterQuality kNone_SkFilterQuality is fastest, typically implemented with nearest neighbor filter. kLow_SkFilterQuality is typically implemented with bilerp filter. kMedium_SkFilterQuality is typically implemented with bilerp filter, and mip-map filter when size is reduced. kHigh_SkFilterQuality is slowest, typically implemented with bicubic filter.

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

Parameters
dstdestination SkPixmap: SkImageInfo, pixels, row bytes
Returns
true if pixels are scaled to fit dst

◆ 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

◆ SkImage_Base

friend class SkImage_Base
friend

◆ SkMipmapBuilder

friend class SkMipmapBuilder
friend

Member Data Documentation

◆ kCompressionTypeCount

constexpr int SkImage::kCompressionTypeCount = static_cast<int>(CompressionType::kLast) + 1
staticconstexpr

◆ kETC1_CompressionType

const CompressionType SkImage::kETC1_CompressionType = CompressionType::kETC2_RGB8_UNORM
static

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