Image

class Image

Image describes a two dimensional array of pixels to draw.

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

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

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

Image may be created from Bitmap, Pixmap, Surface, Picture, encoded streams, GPU texture, YUV_ColorSpace data, or hardware buffer. Encoded streams supported include BMP, GIF, HEIF, ICO, JPEG, PNG, WBMP, WebP. Supported encoding details vary with platform.

skia-python supports a few high-level methods in addition to C++ API:

image = skia.Image.open('/path/to/image.png')
image = image.resize(120, 120)
image = image.convert(alphaType=skia.kUnpremul_AlphaType)
image.save('/path/to/output.jpg', skia.kJPEG)

NumPy arrays can be directly imported or exported:

image = skia.Image.fromarray(array)
array = image.toarray()

General pixel buffers can be exchanged in the following approach:

image = skia.Image.frombytes(pixels, (100, 100))
pixels = image.tobytes()

Classes

`BitDepth`	Members:
`CachingHint`	Members:
`CompressionType`	Members:
`LegacyBitmapMode`	Members:

Methods

`MakeBackendTextureFromImage`	Creates a `GrBackendTexture` from the provided `Image`.
`MakeCrossContextFromPixmap`	Creates `Image` from pixmap.
`MakeFromAdoptedTexture`	Creates `Image` from backendTexture associated with context.
`MakeFromBitmap`	Creates `Image` from bitmap, sharing or copying bitmap pixels.
`MakeFromCompressedTexture`	Creates an `Image` from a GPU backend texture.
`MakeFromEncoded`	Return an image backed by the encoded data, but attempt to defer decoding until the image is actually used/drawn.
`MakeFromPicture`	Creates `Image` from picture.
`MakeFromRaster`	Creates `Image` from pixmap, sharing `Pixmap` pixels.
`MakeFromTexture`	Creates `Image` from GPU texture associated with context.
`MakeFromYUVAPixmaps`	Creates `Image` from `YUVAPixmaps`.
`MakeRasterCopy`	Creates `Image` from `Pixmap` and copy of pixels.
`MakeRasterData`	Creates `Image` from `ImageInfo`, sharing pixels.
`MakeRasterFromCompressed`	Creates a CPU-backed `Image` from compressed data.
`MakeTextureFromCompressed`	Creates a GPU-backed `Image` from compressed data.
`__init__`
`alphaType`	Returns `AlphaType`.
`asLegacyBitmap`	Deprecated.
`bitmap`	Creates `Bitmap` from `Image`.
`bounds`	Returns `IRect` (0, 0, `width()`, `height()`).
`colorSpace`	Returns `ColorSpace`, the range of colors, associated with `Image`.
`colorType`	Returns `ColorType` if known; otherwise, returns `kUnknown_ColorType`.
`convert`	Creates `Image` in target `ColorType`, `AlphatType`, and `ColorSpace`.
`dimensions`	Returns `ISize` (`width()`, `height()`).
`encodeToData`	Overloaded function.
`flush`	Overloaded function.
`flushAndSubmit`	Version of `flush()` that uses a default GrFlushInfo.
`fromarray`	Creates a new `Image` from numpy array.
`frombytes`	Creates a new `Image` from bytes.
`getBackendTexture`	Retrieves the back-end texture.
`hasMipmaps`	Returns true if the image has mipmap levels.
`height`	Returns pixel row count.
`imageInfo`	Returns a `ImageInfo` describing the width, height, color type, alpha type, and color space of the `Image`.
`isAlphaOnly`	Returns true if `Image` pixels represent transparency only.
`isLazyGenerated`	Returns true if `Image` is backed by an image-generator or other service that creates and caches its pixels or texture on-demand.
`isOpaque`	Returns true if pixels ignore their alpha value and are treated as fully opaque.
`isTextureBacked`	Returns true the contents of `Image` was created on or uploaded to GPU memory, and is available as a GPU texture.
`isValid`	Returns true if `Image` can be drawn on either raster surface or GPU surface.
`makeColorSpace`	Creates `Image` in target `ColorSpace`.
`makeColorTypeAndColorSpace`	Experimental.
`makeNonTextureImage`	Returns raster image or lazy image.
`makeRasterImage`	Returns raster image.
`makeRawShader`	Overloaded function.
`makeShader`	Overloaded function.
`makeSubset`	Returns subset of `Image`.
`makeTextureImage`	Returns `Image` backed by GPU texture associated with context.
`makeWithFilter`	Creates filtered `Image`.
`open`	Creates `Image` from file path or file-like object.
`peekPixels`	Copies `Image` pixel address, row bytes, and `ImageInfo` to pixmap, if address is available, and returns true.
`readPixels`	Overloaded function.
`ref`	Increment the reference count.
`refColorSpace`	Returns a smart pointer to `ColorSpace`, the range of colors, associated with `Image`.
`refEncodedData`	Returns encoded `Image` pixels as `Data`, if `Image` was created from supported encoded stream format.
`reinterpretColorSpace`	Creates a new `Image` identical to this one, but with a different `ColorSpace`.
`resize`	Creates `Image` by scaling pixels to fit width and height.
`save`	Saves `Image` to file path or file-like object.
`scalePixels`	Copies `Image` to dst, scaling pixels to fit `dst.width()` and `dst.height()`, and converting pixels to match `dst.colorType()` and `dst.alphaType()`.
`toarray`	Exports a `numpy.ndarray`.
`tobytes`	Creates python bytes object from internal pixels.
`unique`	May return true if the caller is the only owner.
`uniqueID`	Returns value unique to image.
`unref`	Decrement the reference count.
`width`	Returns pixel count in each row.
`withDefaultMipmaps`	Returns an image with the same "base" pixels as the this image, but with mipmap levels automatically generated and attached.

Attributes

`kAllow_CachingHint`
`kBC1_RGB8_UNORM`
`kBC1_RGBA8_UNORM`
`kDisallow_CachingHint`
`kETC2_RGB8_UNORM`
`kF16`
`kLast`
`kNone`
`kRO_LegacyBitmapMode`
`kU8`

Methods

static Image.MakeBackendTextureFromImage(context: skia.GrDirectContext, image: skia.Image, backendTexture: skia.GrBackendTexture) → bool

Creates a GrBackendTexture from the provided Image.

Returns true and stores result in backendTexture if texture is created; otherwise, returns false and leaves backendTexture unmodified.

If Image is both texture backed and singly referenced, image is returned in backendTexture without conversion or making a copy. Image is singly referenced if it was transferred solely using std::move().

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

Parameters:

context (skia.GrContext) – GPU context
image (skia.Image) – Image used for texture
backendTexture (skia.GrBackendTexture) – storage for back-end texture

Returns:

true if back-end texture was created

static Image.MakeCrossContextFromPixmap(context: skia.GrDirectContext, pixmap: SkPixmap, buildMips: bool, limitToMaxTextureSize: bool = False) → skia.Image

Creates Image from pixmap.

Image is uploaded to GPU back-end using context.

Created Image is available to other GPU contexts, and is available across thread boundaries. All contexts must be in the same GPU share group, or otherwise share resources.

When Image is no longer referenced, context releases texture memory asynchronously.

GrBackendTexture created from pixmap is uploaded to match Surface created with dstColorSpace. ColorSpace of Image is determined by pixmap.colorSpace().

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

Parameters:

context (skia.GrDirectContext) – GPU context
pixmap (skia.Pixmap) – ImageInfo, pixel address, and row bytes
buildMips (bool) – create Image as mip map if true
limitToMaxTextureSize (bool) – downscale image to GPU maximum texture size, if necessary

Returns:

created Image, or nullptr

static Image.MakeFromAdoptedTexture(context: skia.GrRecordingContext, backendTexture: skia.GrBackendTexture, origin: skia.GrSurfaceOrigin, colorType: skia.ColorType, alphaType: skia.AlphaType = skia.AlphaType.kPremul_AlphaType, colorSpace: skia.ColorSpace = None) → skia.Image

Creates Image from backendTexture associated with context.

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

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

Parameters:

context (skia.GrContext) – GPU context
backendTexture (skia.GrBackendTexture) – texture residing on GPU
colorSpace (skia.ColorSpace) – range of colors; may be nullptr

Returns:

created Image, or nullptr

static Image.MakeFromBitmap(bitmap: skia.Bitmap) → skia.Image

Creates Image from bitmap, sharing or copying bitmap pixels.

If the bitmap is marked immutable, and its pixel memory is shareable, it may be shared instead of copied.

Image is returned if bitmap is valid. Valid Bitmap parameters include: dimensions are greater than zero; each dimension fits in 29 bits; ColorType and AlphaType are valid, and ColorType is not kUnknown_ColorType; row bytes are large enough to hold one row of pixels; pixel address is not nullptr.

Parameters:: bitmap (skia.Bitmap) – ImageInfo, row bytes, and pixels
Returns:: created Image, or nullptr

static Image.MakeFromCompressedTexture(context: skia.GrRecordingContext, texture: skia.GrBackendTexture, origin: skia.GrSurfaceOrigin, alphaType: skia.AlphaType, colorSpace: skia.ColorSpace = None) → skia.Image

Creates an Image from a GPU backend texture.

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

Parameters:

context (skia.GrRecordingContext) – the GPU context
backendTexture (skia.GrBackendTexture) – a texture already allocated by the GPU
alphaType (skia.AlphaType) – This 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_AlphaType.
colorSpace (skia.ColorSpace) – This 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., ColorSpace.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., ColorSpace.MakeSRGB() ).

Returns:

created Image, or nullptr

static Image.MakeFromEncoded(encoded: skia.Data, alphaType: skia.AlphaType | None = None) → skia.Image

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.

If the encoded format is not supported, nullptr is returned.

Parameters:: encoded – the encoded data
Returns:: created Image, or nullptr

static Image.MakeFromPicture(picture: SkPicture, dimensions: skia.ISize, matrix: skia.Matrix = None, paint: SkPaint = None, bitDepth: skia.Image.BitDepth = skia.Image.BitDepth.kU8, colorSpace: skia.ColorSpace = None) → skia.Image

Creates Image from picture.

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

If matrix is nullptr, draws with identity Matrix. If paint is nullptr, draws with default Paint. colorSpace may be nullptr.

Parameters:

picture (skia.Picture) – stream of drawing commands
dimensions (skia.ISize) – width and height
matrix (skia.Matrix) – Matrix to rotate, scale, translate, and so on; may be nullptr
paint (skia.Paint) – Paint to apply transparency, filtering, and so on; may be nullptr
bitDepth (skia.Image.BitDepth) – 8-bit integer or 16-bit float: per component
colorSpace (skia.ColorSpace) – range of colors; may be nullptr

Returns:

created Image, or nullptr

static Image.MakeFromRaster(pixmap: SkPixmap) → skia.Image

Creates Image from pixmap, sharing Pixmap pixels.

Image is returned if pixmap is valid. Valid Pixmap parameters include: dimensions are greater than zero; each dimension fits in 29 bits; ColorType and AlphaType are valid, and ColorType is not kUnknown_ColorType; row bytes are large enough to hold one row of pixels; pixel address is not nullptr.

Parameters:: pixmap (skia.Pixmap) – ImageInfo, pixel address, and row bytes
Returns:: Image sharing pixmap

static Image.MakeFromTexture(context: skia.GrRecordingContext, texture: skia.GrBackendTexture, origin: skia.GrSurfaceOrigin, colorType: skia.ColorType, alphaType: skia.AlphaType, colorSpace: skia.ColorSpace = None) → skia.Image

Creates Image from GPU texture associated with context.

Caller is responsible for managing the lifetime of GPU texture.

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

Parameters:

context (skia.GrRecordingContext) – GPU context
backendTexture (skia.GrBackendTexture) – texture residing on GPU
colorSpace (skia.ColorSpace) – range of colors; may be nullptr

Returns:

created Image, or nullptr

static Image.MakeFromYUVAPixmaps(context: skia.GrRecordingContext, pixmaps: SkYUVAPixmaps, buildMips: skia.GrMipmapped = skia.GrMipmapped.kNo, limitToMaxTextureSize: bool = False, imageColorSpace: skia.ColorSpace = None) → skia.Image

Creates Image from YUVAPixmaps.

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

YUVAPixmaps has a YUVAInfo which specifies the transformation from YUV to RGB. The ColorSpace of the resulting RGB values is specified by imageColorSpace. This will be the ColorSpace 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.

YUVAPixmaps does not need to remain valid after this returns.

Parameters:

context – GPU context
pixmaps – The planes as pixmaps with supported YUVAInfo that specifies conversion to RGB.
buildMips – create internal YUVA textures as mip map if kYes. This is silently ignored if the context does not support mip maps.
limitToMaxTextureSize – downscale image to GPU maximum texture size, if necessary
imageColorSpace – range of colors of the resulting image; may be nullptr

Returns:

created Image, or nullptr

static Image.MakeRasterCopy(pixmap: SkPixmap) → skia.Image

Creates Image from Pixmap and copy of pixels.

Since pixels are copied, Pixmap pixels may be modified or deleted without affecting Image.

Image is returned if Pixmap is valid. Valid Pixmap parameters include: dimensions are greater than zero; each dimension fits in 29 bits; ColorType and AlphaType are valid, and ColorType is not kUnknown_ColorType; row bytes are large enough to hold one row of pixels; pixel address is not nullptr.

Parameters:: pixmap (skia.Pixmap) – ImageInfo, pixel address, and row bytes
Returns:: copy of Pixmap pixels, or nullptr

static Image.MakeRasterData(info: skia.ImageInfo, pixels: Buffer, rowBytes: int) → skia.Image

Creates Image from ImageInfo, sharing pixels.

Image is returned if ImageInfo is valid. Valid ImageInfo parameters include: dimensions are greater than zero; each dimension fits in 29 bits; ColorType and AlphaType are valid, and ColorType is not kUnknown_ColorType; rowBytes are large enough to hold one row of pixels; pixels is not nullptr, and contains enough data for Image.

Parameters:

info (skia.ImageInfo) – contains width, height, AlphaType, ColorType, ColorSpace
pixels (Union[bytes,bytearray,memoryview]) – pixel storage
rowBytes (int) – size of pixel row or larger

Returns:

Image sharing pixels, or nullptr

static Image.MakeRasterFromCompressed(data: skia.Data, width: int, height: int, type: skia.Image.CompressionType) → skia.Image

Creates a CPU-backed Image 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:

data (skia.Data) – compressed data to store in SkImage
width (int) – width of full SkImage
height (int) – height of full SkImage
type (skia.Image.CompressionType) – type of compression used

Returns:

created Image, or nullptr

static Image.MakeTextureFromCompressed(context: skia.GrDirectContext, data: skia.Data, width: int, height: int, type: skia.Image.CompressionType, mipMapped: skia.GrMipmapped = skia.GrMipmapped.kNo, isProtected: skia.GrProtected = skia.GrProtected.kNo) → skia.Image

Creates a GPU-backed Image from compressed data.

This method will return an Image 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:

context (skia.GrDirectContext) – GPU context
data (skia.Data) – compressed data to store in Image
width (int) – width of full Image
height (int) – height of full Image
type (skia.CompressionType) – type of compression used
mipMapped (skia.skgpu::Mipmapped) – does ‘data’ contain data for all the mipmap levels?
isProtected (skia.GrProtected) – do the contents of ‘data’ require DRM protection (on Vulkan)?

Returns:

created Image, or nullptr

Image.__init__(*args, **kwargs)

Image.alphaType(self: skia.Image) → skia.AlphaType

Returns AlphaType.

AlphaType returned was a parameter to an Image constructor, or was parsed from encoded data.

Returns:: AlphaType in Image

Image.asLegacyBitmap(self: skia.Image, bitmap: skia.Bitmap, legacyBitmapMode: skia.Image.LegacyBitmapMode = skia.Image.kRO_LegacyBitmapMode) → bool

Deprecated.

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

Parameters:

bitmap – storage for legacy Bitmap
legacyBitmapMode – bitmap is read-only and immutable

Returns:

true if Bitmap was created

Image.bitmap(self: skia.Image, colorType: skia.ColorType = skia.ColorType.kUnknown_ColorType, alphaType: skia.AlphaType = skia.AlphaType.kUnknown_AlphaType, colorSpace: skia.ColorSpace = None) → skia.Bitmap

Creates Bitmap from Image.

Pixels are always allocated and copied.

Parameters:

colorType – color type of Bitmap. If kUnknown_ColorType, uses the same colorType as Image.
alphaType – alpha type of Bitmap. If kUnknown_AlphaType, uses the same alphaType as Image.
colorSpace – color space of Bitmap.

Returns:

Bitmap

Image.bounds(self: skia.Image) → skia.IRect

Returns IRect (0, 0, width(), height()).

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

Image.colorSpace(self: skia.Image) → skia.ColorSpace

Returns ColorSpace, the range of colors, associated with Image.

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

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

Returns:: ColorSpace in Image, or nullptr

Image.colorType(self: skia.Image) → skia.ColorType

Returns ColorType if known; otherwise, returns kUnknown_ColorType.

Returns:: ColorType of Image

Image.convert(self: skia.Image, colorType: skia.ColorType = skia.ColorType.kUnknown_ColorType, alphaType: skia.AlphaType = skia.AlphaType.kUnknown_AlphaType, colorSpace: skia.ColorSpace = None) → skia.Image

Creates Image in target ColorType, AlphatType, and ColorSpace. Raises if Image could not be created.

Pixels are converted only if pixel conversion is possible. If Image ColorType is kGray_8_ColorType, or kAlpha_8_ColorType; colorType must be the same. If Image ColorType is kGray_8_ColorType, colorSpace must be the same. If Image AlphaType is kOpaque_AlphaType, alphaType must be the same. If Image ColorSpace is nullptr, colorSpace must be the same. Raises if pixel conversion is not possible.

Parameters:

colorType – target color type. If kUnknown_ColorType is given, uses the same colorType as Image.
alphaType – target alpha type. If kUnknown_AlphaType is given, uses the same alphaType as Image.
colorSpace – target color space.

Returns:

Image

Image.dimensions(self: skia.Image) → skia.ISize

Returns ISize (width(), height()).

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

Image.encodeToData(*args, **kwargs)

Overloaded function.

encodeToData(self: skia.Image, encodedImageFormat: skia.EncodedImageFormat, quality: int) -> skia.Data

Encodes Image pixels, returning result as Data.

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

Image encoding in a format requires both building with one or more of: SK_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: kICO, kBMP, 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.

param skia.EncodedImageFormat encodedImageFormat:

one of: kJPEG, kPNG, kWEBP

param int quality:

encoder specific metric with 100 equaling best

return:

encoded Image, or nullptr
encodeToData(self: skia.Image) -> skia.Data

Encodes Image pixels, returning result as Data.

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

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

return:

encoded Image, or nullptr

Image.flush(*args, **kwargs)

Overloaded function.

flush(self: skia.Image, arg0: skia.GrDirectContext, arg1: skia.GrFlushInfo) -> skia.GrSemaphoresSubmitted

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.

param context:

the context on which to flush pending usages of the image.

param info:

flush options
flush(self: skia.Image, context: skia.GrDirectContext) -> None

Image.flushAndSubmit(self: skia.Image, context: skia.GrDirectContext) → None

Version of flush() that uses a default GrFlushInfo.

Also submits the flushed work to the GPU.

static Image.fromarray(array: numpy.ndarray, colorType: skia.ColorType = skia.ColorType.kN32_ColorType, alphaType: skia.AlphaType = skia.AlphaType.kUnpremul_AlphaType, colorSpace: skia.ColorSpace = None, copy: bool = True) → skia.Image

Creates a new Image from numpy array.

Parameters:

array (numpy.ndarray) – numpy ndarray of shape=(height, width, channels) and appropriate dtype. Must have non-zero width and height, and the valid number of channels for the specified color type.
colorType (skia.ColorType) – color type of the array
alphaType (skia.AlphaType) – alpha type of the array
colorSpace (skia.ColorSpace) – range of colors; may be nullptr
copy (bool) – Whether to copy pixels.

static Image.frombytes(array: Buffer, dimensions: skia.ISize, colorType: skia.ColorType = skia.ColorType.kN32_ColorType, alphaType: skia.AlphaType = skia.AlphaType.kUnpremul_AlphaType, colorSpace: skia.ColorSpace = None, copy: bool = True) → skia.Image

Creates a new Image from bytes.

Parameters:

pixels – raw bytes of pixels
dimensions (skia.ISize) – (width, height) tuple
colorType (skia.ColorType) – color type of the array
alphaType (skia.AlphaType) – alpha type of the array
colorSpace (skia.ColorSpace) – range of colors; may be nullptr
copy (bool) – Whether to copy pixels. When false is specified, Image shares the pixel buffer without copy.

Image.getBackendTexture(self: skia.Image, flushPendingGrContextIO: bool, origin: skia.GrSurfaceOrigin = None) → bool

Retrieves the back-end texture. If Image has no back-end texture, an invalid object is returned. Call GrBackendTexture.isValid() to determine if the result is valid.

If flushPendingGrContextIO is true, completes deferred I/O operations.

If origin in not nullptr, copies location of content drawn into Image.

Parameters:: flushPendingGrContextIO – flag to flush outstanding requests
Returns:: back-end API texture handle; invalid on failure

Image.hasMipmaps(self: skia.Image) → bool: Returns true if the image has mipmap levels.

Image.height(self: skia.Image) → int

Returns pixel row count.

Returns:: pixel height in Image

Image.imageInfo(self: skia.Image) → skia.ImageInfo

Returns a ImageInfo describing the width, height, color type, alpha type, and color space of the Image.

Returns:: image info of Image.

Image.isAlphaOnly(self: skia.Image) → bool

Returns true if Image pixels represent transparency only.

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

Returns:: true if pixels represent a transparency mask

Image.isLazyGenerated(self: skia.Image) → bool

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

Returns:: true if Image is created as needed

Image.isOpaque(self: skia.Image) → bool

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

Returns:: true if AlphaType is kOpaque_AlphaType

Image.isTextureBacked(self: skia.Image) → bool

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

Returns:: true if Image is a GPU texture

Image.isValid(self: skia.Image, context: skia.GrRecordingContext = None) → bool

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

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

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

Parameters:: context (skia.GrRecordingContext) – GPU context
Returns:: true if Image can be drawn

Image.makeColorSpace(self: skia.Image, target: skia.ColorSpace, direct: skia.GrDirectContext = None) → skia.Image

Creates Image in target ColorSpace.

Returns nullptr if Image could not be created.

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

Parameters:: target (skia.ColorSpace) – ColorSpace describing color range of returned Image
Returns:: created Image in target ColorSpace

Image.makeColorTypeAndColorSpace(self: skia.Image, targetColorType: skia.ColorType, targetColorSpace: skia.ColorSpace = None, direct: skia.GrDirectContext = None) → skia.Image

Experimental.

Creates Image in target ColorType and ColorSpace. Returns nullptr if Image could not be created.

Returns original Image if it is in target ColorType and ColorSpace.

Parameters:

targetColorType (skia.ColorType) – ColorType of returned Image
targetColorSpace (skia.ColorSpace) – ColorSpace of returned Image

Returns:

created Image in target ColorType and ColorSpace

Image.makeNonTextureImage(self: skia.Image, context: skia.GrDirectContext = None) → skia.Image

Returns raster image or lazy image.

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

Returns nullptr if backed by GPU texture and copy fails.

Returns:: raster image, lazy image, or nullptr

Image.makeRasterImage(self: skia.Image, cachingHint: skia.Image.CachingHint = skia.Image.CachingHint.kAllow_CachingHint) → skia.Image

Returns raster image.

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

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

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

Parameters:: cachingHint (skia.Image.CachingHint) – Caching hint
Returns:: raster image, or nullptr

Image.makeRawShader(*args, **kwargs)

Overloaded function.

makeRawShader(self: skia.Image, tmx: skia.TileMode = skia.TileMode.kClamp, tmy: skia.TileMode = skia.TileMode.kClamp, samplingOptions: skia.SamplingOptions = skia.SamplingOptions(), localMatrix: skia.Matrix = None) -> SkShader

Creates Shader from Image.

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

Shader dimensions are taken from Image. Shader uses TileMode rules to fill drawn area outside Image. localMatrix permits transforming Image before Canvas matrix is applied.

param skia.TileMode tmx:

tiling in the x direction

param skia.TileMode tmy:

tiling in the y direction

param skia.Matrix localMatrix:

Image transformation, or nullptr

return:

Shader containing Image
makeRawShader(self: skia.Image, tmx: skia.TileMode = skia.TileMode.kClamp, tmy: skia.TileMode = skia.TileMode.kClamp, samplingOptions: skia.SamplingOptions = skia.SamplingOptions(), localMatrix: skia.Matrix) -> SkShader

Creates Shader from Image.

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

Shader dimensions are taken from Image. Shader uses TileMode rules to fill drawn area outside Image. localMatrix permits transforming Image before Canvas matrix is applied.

param skia.TileMode tmx:

tiling in the x direction

param skia.TileMode tmy:

tiling in the y direction

param skia.Matrix localMatrix:

Image transformation, or nullptr

return:

Shader containing Image
makeRawShader(self: skia.Image, samplingOptions: skia.SamplingOptions = skia.SamplingOptions(), localMatrix: skia.Matrix) -> SkShader

Creates Shader from Image.

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

Shader dimensions are taken from Image. localMatrix permits transforming Image before Canvas matrix is applied.

param skia.Matrix localMatrix:

Image transformation, or nullptr

return:

Shader containing Image
makeRawShader(self: skia.Image, samplingOptions: skia.SamplingOptions = skia.SamplingOptions(), localMatrix: skia.Matrix = None) -> SkShader

Creates Shader from Image.

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

Shader dimensions are taken from Image. localMatrix permits transforming Image before Canvas matrix is applied.

param skia.Matrix localMatrix:

Image transformation, or nullptr

return:

Shader containing Image

Image.makeShader(*args, **kwargs)

Overloaded function.

makeShader(self: skia.Image, tmx: skia.TileMode = skia.TileMode.kClamp, tmy: skia.TileMode = skia.TileMode.kClamp, samplingOptions: skia.SamplingOptions = skia.SamplingOptions(), localMatrix: skia.Matrix = None) -> SkShader

Creates Shader from Image.

Shader dimensions are taken from Image. Shader uses TileMode rules to fill drawn area outside Image. localMatrix permits transforming Image before Canvas matrix is applied.

param skia.TileMode tmx:

tiling in the x direction

param skia.TileMode tmy:

tiling in the y direction

param skia.Matrix localMatrix:

Image transformation, or nullptr

return:

Shader containing Image
makeShader(self: skia.Image, tmx: skia.TileMode = skia.TileMode.kClamp, tmy: skia.TileMode = skia.TileMode.kClamp, samplingOptions: skia.SamplingOptions = skia.SamplingOptions(), localMatrix: skia.Matrix) -> SkShader

Creates Shader from Image.

Shader dimensions are taken from Image. Shader uses TileMode rules to fill drawn area outside Image. localMatrix permits transforming Image before Canvas matrix is applied.

param skia.TileMode tmx:

tiling in the x direction

param skia.TileMode tmy:

tiling in the y direction

param skia.Matrix localMatrix:

Image transformation, or nullptr

return:

Shader containing Image
makeShader(self: skia.Image, samplingOptions: skia.SamplingOptions = skia.SamplingOptions(), localMatrix: skia.Matrix) -> SkShader

Creates Shader from Image.

Shader dimensions are taken from Image. localMatrix permits transforming Image before Canvas matrix is applied.

param skia.Matrix localMatrix:

Image transformation, or nullptr

return:

Shader containing Image
makeShader(self: skia.Image, samplingOptions: skia.SamplingOptions = skia.SamplingOptions(), localMatrix: skia.Matrix = None) -> SkShader

Creates Shader from Image.

Shader dimensions are taken from Image. localMatrix permits transforming Image before Canvas matrix is applied.

param skia.Matrix localMatrix:

Image transformation, or nullptr

return:

Shader containing Image

Image.makeSubset(self: skia.Image, subset: skia.IRect, direct: skia.GrDirectContext = None) → skia.Image

Returns subset of Image.

subset must be fully contained by Image dimensions(). The implementation may share pixels, or may copy them.

Returns nullptr if subset is empty, or subset is not contained by bounds, or pixels in Image could not be read or copied.

Parameters:: subset (skia.IRect) – bounds of returned Image
Returns:: partial or full Image, or nullptr

Image.makeTextureImage(self: skia.Image, context: skia.GrDirectContext, mipMapped: skia.GrMipmapped = skia.GrMipmapped.kNo, budgeted: skia.Budgeted = skia.Budgeted.kYes) → skia.Image

Returns Image backed by GPU texture associated with context.

Returned Image is compatible with Surface created with dstColorSpace. The returned Image respects mipMapped setting; if mipMapped equals skgpu::Mipmapped.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 Image if the image is already texture-backed, the context matches, and mipMapped is compatible with the backing GPU texture. Budgeted is ignored in this case.

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

Parameters:

context (GrDirectContext) – the GrDirectContext in play, if it exists
mipMapped (skgpu::Mipmapped) – whether created Image texture must allocate mip map levels
budgeted (skia.Budgeted) – whether to count a newly created texture for the returned image counts against the GrDirectContext’s budget.

Returns:

created Image, or nullptr

Image.makeWithFilter(self: skia.Image, context: skia.GrRecordingContext, filter: SkImageFilter, subset: skia.IRect, clipBounds: skia.IRect, outSubset: skia.IRect, offset: skia.IPoint) → skia.Image

Creates filtered Image.

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

Returns nullptr if Image could not be created. If nullptr is returned, outSubset and offset are undefined.

Useful for animation of ImageFilter that varies size from frame to frame. Returned Image is created larger than required by filter so that GPU texture can be reused with different sized effects. outSubset describes the valid bounds of GPU texture returned. offset translates the returned Image to keep subsequent animation frames aligned with respect to each other.

Parameters:

context (skia.GrRecordingContext) – the GrRecordingContext in play - if it exists
filter (skia.ImageFilter) – how Image is sampled when transformed
subset (skia.IRect) – bounds of Image processed by filter
clipBounds (skia.IRect) – expected bounds of filtered Image
outSubset (skia.IRect) – output for returned Image bounds
offset (skia.IPoint) – output for returned Image translation

Returns:

filtered Image, or nullptr

static Image.open(fp: object) → skia.Image

Creates Image from file path or file-like object.

Shortcut for the following:

if hasattr(fp, 'read') and hasattr(fp, 'seek'):
    fp.seek(0)
    data = skia.Data.MakeWithCopy(fp.read())
else:
    data = skia.Data.MakeFromFileName(fp)
image = skia.Image.MakeFromEncoded(data)

Parameters:: fp – file path or file-like object that has seek and read method. file must be opened in binary mode.

Image.peekPixels(self: skia.Image, pixmap: SkPixmap) → bool

Copies Image pixel address, row bytes, and ImageInfo to pixmap, if address is available, and returns true.

If pixel address is not available, return false and leave pixmap unchanged.

Parameters:: pixmap (skia.Pixmap) – storage for pixel state if pixels are readable; otherwise, ignored
Returns:: true if Image has direct access to pixels

Image.readPixels(*args, **kwargs)

Overloaded function.

readPixels(self: skia.Image, context: skia.GrDirectContext, dstInfo: skia.ImageInfo, dstPixels: Buffer, dstRowBytes: int, srcX: int = 0, srcY: int = 0, cachingHint: skia.Image.CachingHint = skia.Image.CachingHint.kAllow_CachingHint) -> bool
Copies a Rect of pixels from Image to dst. Copy starts at (srcX, srcY), and does not exceed Image (width(), height()).

dstInfo specifies width, height, ColorType, AlphaType, and ColorSpace of destination. dstRowBytes specifics the gap from one destination row to the next. Returns true if pixels are copied. Returns false if:
- dstInfo.addr() equals nullptr
- dstRowBytes is less than dstInfo.minRowBytes()
- PixelRef is nullptr
Pixels are copied only if pixel conversion is possible. If Image ColorType is kGray_8_ColorType, or kAlpha_8_ColorType; dst.colorType() must match. If Image ColorType is kGray_8_ColorType, dst.colorSpace() must match. If Image AlphaType is kOpaque_AlphaType, dst.alphaType() must match. If Image ColorSpace 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.

param context:

the GrDirectContext in play, if it exists

param dstInfo:

destination width, height, pixels, ColorType, AlphaType, ColorSpace

param dstPixels:

destination pixel storage

param dstRowBytes:

destination row length

param srcX:

column index whose absolute value is less than width()

param srcY:

row index whose absolute value is less than height()

param cachingHint:

whether the pixels should be cached locally

return:

true if pixels are copied to dstPixels
readPixels(self: skia.Image, context: skia.GrDirectContext, dst: SkPixmap, srcX: int, srcY: int, cachingHint: skia.Image.CachingHint = skia.Image.CachingHint.kAllow_CachingHint) -> bool
Copies a Rect of pixels from Image to dst. Copy starts at (srcX, srcY), and does not exceed Image (width(), height()).

dst specifies width, height, ColorType, AlphaType, ColorSpace, 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 ImageInfo.minRowBytes()
- PixelRef is nullptr
Pixels are copied only if pixel conversion is possible. If Image ColorType is kGray_8_ColorType, or kAlpha_8_ColorType; dst.colorType() must match. If Image ColorType is kGray_8_ColorType, dst.colorSpace() must match. If Image AlphaType is kOpaque_AlphaType, dst.alphaType() must match. If Image ColorSpace 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.

param context:

the GrDirectContext in play, if it exists

param dst:

destination Pixmap: ImageInfo, pixels, row bytes

param srcX:

column index whose absolute value is less than width()

param srcY:

row index whose absolute value is less than height()

param cachingHint:

whether the pixels should be cached locally

return:

true if pixels are copied to dst
readPixels(self: skia.Image, dstInfo: skia.ImageInfo, dstPixels: Buffer, dstRowBytes: int, srcX: int = 0, srcY: int = 0, cachingHint: skia.Image.CachingHint = skia.Image.CachingHint.kAllow_CachingHint) -> bool

Deprecated. Use the variants that accept a GrDirectContext.
readPixels(self: skia.Image, dst: SkPixmap, srcX: int, srcY: int, cachingHint: skia.Image.CachingHint = skia.Image.CachingHint.kAllow_CachingHint) -> bool

Deprecated. Use the variants that accept a GrDirectContext.

Image.ref(self: skia.RefCntBase) → None

Increment the reference count.

Must be balanced by a call to unref().

Image.refColorSpace(self: skia.Image) → skia.ColorSpace

Returns a smart pointer to ColorSpace, the range of colors, associated with Image.

The smart pointer tracks the number of objects sharing this ColorSpace reference so the memory is released when the owners destruct.

The returned ColorSpace is immutable.

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

Returns:: ColorSpace in Image, or nullptr, wrapped in a smart pointer

Image.refEncodedData(self: skia.Image) → skia.Data

Returns encoded Image pixels as Data, if Image 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 Image contents are not encoded.

Returns:: encoded Image, or nullptr

Image.reinterpretColorSpace(self: skia.Image, newColorSpace: skia.ColorSpace = None) → skia.Image

Creates a new Image identical to this one, but with a different ColorSpace.

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

Image.resize(self: skia.Image, width: int, height: int, options: skia.SamplingOptions = skia.SamplingOptions(), cachingHint: skia.Image.CachingHint = skia.Image.CachingHint.kAllow_CachingHint) → skia.Image

Creates Image by scaling pixels to fit width and height. Raises if Image could not be scaled.

Scales the image, with filterQuality, to match width and height. filterQuality None_FilterQuality is fastest, typically implemented with nearest neighbor filter. kLow_FilterQuality is typically implemented with bilerp filter. kMedium_FilterQuality is typically implemented with bilerp filter, and mip-map filter when size is reduced. kHigh_FilterQuality 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:

width (int) – target width
height (int) – target height
options (skia.SamplingOptions) – sampling options
cachingHint (skia.Image.CachingHint) – Caching hint

Returns:

Image

Image.save(self: skia.Image, fp: object, encodedImageFormat: skia.EncodedImageFormat = skia.EncodedImageFormat.kPNG, quality: int = 100) → None

Saves Image to file path or file-like object.

Shortcut for the following:

data = image.encodeToData(encodedImageFormat, quality)
if hasattr(fp, 'write'):
    fp.write(data)
else:
    with open(fp, 'wb') as f:
        f.write(data)

Parameters:

fp – file path or file-like object that has write method. file must be opened in writable binary mode.
encodedImageFormat (skia.EncodedImageFormat) – one of: kJPEG, kPNG, kWEBP
quality (int) – encoder specific metric with 100 equaling best

Image.scalePixels(self: skia.Image, dst: SkPixmap, samplingOptions: skia.SamplingOptions = skia.SamplingOptions(), cachingHint: skia.Image.CachingHint = skia.Image.CachingHint.kAllow_CachingHint) → bool

Copies Image to dst, scaling pixels to fit dst.width() and dst.height(), and converting pixels to match dst.colorType() and dst.alphaType().

Returns true if pixels are copied. Returns false if dst.addr() is nullptr, or dst.rowBytes() is less than dst ImageInfo.minRowBytes().

Pixels are copied only if pixel conversion is possible. If Image ColorType is kGray_8_ColorType, or kAlpha_8_ColorType; dst.colorType() must match. If Image ColorType is kGray_8_ColorType, dst.colorSpace() must match. If Image AlphaType is kOpaque_AlphaType, dst.alphaType() must match. If Image ColorSpace 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 None_FilterQuality is fastest, typically implemented with nearest neighbor filter. kLow_FilterQuality is typically implemented with bilerp filter. kMedium_FilterQuality is typically implemented with bilerp filter, and mip-map filter when size is reduced. kHigh_FilterQuality 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:

dst (skia.Pixmap) – destination Pixmap: ImageInfo, pixels, row bytes
filterQuality (skia.FilterQuality) – Filter quality
cachingHint (skia.Image.CachingHint) – Caching hint

Returns:

true if pixels are scaled to fit dst

Image.toarray(self: skia.Image, srcX: int = 0, srcY: int = 0, colorType: skia.ColorType = skia.ColorType.kUnknown_ColorType, alphaType: skia.AlphaType = skia.AlphaType.kUnpremul_AlphaType, colorSpace: skia.ColorSpace = None) → numpy.ndarray

Exports a numpy.ndarray.

Parameters:

srcX – offset into readable pixels on x-axis; may be negative
srcY – offset into readable pixels on y-axis; may be negative
colorType – target ColorType
alphaType – target AlphaType
colorSpace – target ColorSpace

Returns:

numpy.ndarray

Image.tobytes(self: skia.Image) → object

Creates python bytes object from internal pixels.

When the image is raster, the returned bytes share the internal buffer. Otherwise, pixels are copied to a newly allocated python bytes.

Image.unique(self: skia.RefCntBase) → bool

May return true if the caller is the only owner.

Ensures that all previous owner’s actions are complete.

Image.uniqueID(self: skia.Image) → int

Returns value unique to image.

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

Returns:: unique identifier

Image.unref(self: skia.RefCntBase) → None

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.

Image.width(self: skia.Image) → int

Returns pixel count in each row.

Returns:: pixel width in Image

Image.withDefaultMipmaps(self: skia.Image) → skia.Image: Returns an image with the same “base” pixels as the this image, but with mipmap levels automatically generated and attached.

Attributes

Image.kAllow_CachingHint = <CachingHint.kAllow_CachingHint: 0>

Image.kBC1_RGB8_UNORM = <CompressionType.kBC1_RGB8_UNORM: 2>

Image.kBC1_RGBA8_UNORM = <CompressionType.kBC1_RGBA8_UNORM: 3>

Image.kDisallow_CachingHint = <CachingHint.kDisallow_CachingHint: 1>

Image.kETC2_RGB8_UNORM = <CompressionType.kETC2_RGB8_UNORM: 1>

Image.kF16 = <BitDepth.kF16: 1>

Image.kLast = <CompressionType.kBC1_RGBA8_UNORM: 3>

Image.kNone = <CompressionType.kNone: 0>

Image.kRO_LegacyBitmapMode = <LegacyBitmapMode.kRO_LegacyBitmapMode: 0>

Image.kU8 = <BitDepth.kU8: 0>