Pixmap

class Pixmap

Pixmap provides a utility to pair ImageInfo with pixels and row bytes.

Pixmap is a low level class which provides convenience functions to access raster destinations. Canvas can not draw Pixmap, nor does Pixmap provide a direct drawing destination.

Use Bitmap to draw pixels referenced by Pixmap; use Surface to draw into pixels referenced by Pixmap.

Pixmap does not try to manage the lifetime of the pixel memory. Use PixelRef to manage pixel memory; PixelRef is safe across threads.

Pixmap supports buffer protocol. It is possible to mount Pixmap as array:

array = np.array(pixmap, copy=False)

Or mount array as Pixmap with ImageInfo:

buffer = np.zeros((100, 100, 4), np.uint8)
array = skia.Pixmap(skia.ImageInfo.MakeN32Premul(100, 100), buffer)

Methods

__init__	Overloaded function.
addr	Returns pixel address, the base address corresponding to the pixel origin.
addr16	Returns readable base pixel address.
addr32	Returns readable base pixel address.
addr64	Returns readable base pixel address.
addr8	Returns readable base pixel address.
alphaType
bounds	Returns IRect ( 0, 0, width(), height() ).
colorSpace	Returns ColorSpace, the range of colors, associated with ImageInfo.
colorType
computeByteSize	Returns minimum memory required for pixel storage.
computeIsOpaque	Returns true if all pixels are opaque.
dimensions	Return the dimensions of the pixmap (from its ImageInfo)
erase	Writes color to pixels bounded by subset; returns true on success.
extractSubset	Sets subset width, height, pixel address to intersection of Pixmap with area, if intersection is not empty; and return true.
getAlphaf	Look up the pixel at (x,y) and return its alpha component, normalized to [0..1].
getColor	Returns pixel at (x, y) as unpremultiplied color.
height	Returns pixel row count.
info	Returns width, height, AlphaType, ColorType, and ColorSpace.
isOpaque	Returns true if AlphaType is kOpaque_AlphaType.
readPixels	Overloaded function.
refColorSpace	Returns smart pointer to ColorSpace, the range of colors, associated with ImageInfo.
reset	Overloaded function.
rowBytes	Returns row bytes, the interval from one pixel row to the next.
rowBytesAsPixels	Returns number of pixels that fit on row.
scalePixels	Copies Pixmap to dst, scaling pixels to fit dst.width() and dst.height(), and converting pixels to match dst.colorType() and dst.alphaType().
setColorSpace	Changes ColorSpace in ImageInfo; preserves width, height, AlphaType, and ColorType in Image, and leaves pixel address and row bytes unchanged.
shiftPerPixel	Returns bit shift converting row bytes to row pixels.
tobytes
width	Returns pixel count in each pixel row.
writable_addr	Returns writable base pixel address.

Methods

Pixmap.__init__(*args, **kwargs)

Overloaded function.

1. __init__(self: skia.Pixmap) -> None

   Creates an empty Pixmap without pixels, with kUnknown_ColorType, with kUnknown_AlphaType, and with a width and height of zero.

   Use reset() to associate pixels, ColorType, AlphaType, width, and height after Pixmap has been created.

   return:

   empty Pixmap

2. __init__(self: skia.Pixmap, info: skia.ImageInfo, data: object, rowBytes: int) -> None

   Creates Pixmap from info width, height, AlphaType, and ColorType.

   data points to pixels, or nullptr. rowBytes should be info.width() times info.bytesPerPixel(), or larger.

   No parameter checking is performed; it is up to the caller to ensure that data and rowBytes agree with info.

   The memory lifetime of pixels is managed by the caller. When Pixmap goes out of scope, data is unaffected.

   Pixmap may be later modified by reset() to change its size, pixel type, or storage.

   info:

   width, height, AlphaType, ColorType of ImageInfo

   data:

   pointer to pixels allocated by caller; may be nullptr

   rowBytes:

   size of one row of data; width times pixel size, or larger

3. __init__(self: skia.Pixmap, array: numpy.ndarray, colorType: skia.ColorType = skia.ColorType.kN32_ColorType, alphaType: skia.AlphaType = skia.AlphaType.kUnpremul_AlphaType, colorSpace: skia.ColorSpace = None) -> None

   Creates Pixmap backed by numpy array.

   The memory lifetime of pixels is managed by the caller. When Pixmap goes out of scope, data is unaffected.

   array:

   numpy ndarray of shape=(height, width, channels). Must have non-zero width and height, and the valid number of channels for the specified color type.

   colorType:

   color type of the array

   alphaType:

   alpha type of the array

   colorSpace:

   range of colors; may be nullptr

Pixmap.addr(self: skia.Pixmap) → memoryview

Returns pixel address, the base address corresponding to the pixel origin.

It is up to the Pixmap creator to ensure that pixel address is a useful value.

Returns:

pixel address

Return type:

memoryview

Pixmap.addr16(self: skia.Pixmap) → memoryview

Returns readable base pixel address.

Result is addressable as unsigned 16-bit words. Will trigger an assert() if ColorType is not kRGB_565_ColorType or kARGB_4444_ColorType, and is built with SK_DEBUG defined.

One word corresponds to one pixel.

Returns:

readable unsigned 16-bit pointer to pixels

Return type:

memoryview

Pixmap.addr32(self: skia.Pixmap) → memoryview

Returns readable base pixel address.

Result is addressable as unsigned 32-bit words. Will trigger an assert() if ColorType is not kRGBA_8888_ColorType or kBGRA_8888_ColorType, and is built with SK_DEBUG defined.

One word corresponds to one pixel.

Returns:

readable unsigned 32-bit pointer to pixels

Return type:

memoryview

Pixmap.addr64(self: skia.Pixmap) → memoryview

Returns readable base pixel address.

Result is addressable as unsigned 64-bit words. Will trigger an assert() if ColorType is not kRGBA_F16_ColorType and is built with SK_DEBUG defined.

One word corresponds to one pixel.

Returns:

readable unsigned 64-bit pointer to pixels

Return type:

memoryview

Pixmap.addr8(self: skia.Pixmap) → memoryview

Returns readable base pixel address.

Result is addressable as unsigned 8-bit bytes. Will trigger an assert() if ColorType is not kAlpha_8_ColorType or kGray_8_ColorType, and is built with SK_DEBUG defined.

One byte corresponds to one pixel.

Returns:

readable unsigned 8-bit pointer to pixels

Return type:

memoryview

Pixmap.alphaType(self: skia.Pixmap) → skia.AlphaType

Pixmap.bounds(self: skia.Pixmap) → skia.IRect

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

Returns:

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

Pixmap.colorSpace(self: skia.Pixmap) → skia.ColorSpace

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

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

Returns:

ColorSpace in ImageInfo, or nullptr

Pixmap.colorType(self: skia.Pixmap) → skia.ColorType

Pixmap.computeByteSize(self: skia.Pixmap) → int

Returns minimum memory required for pixel storage.

Does not include unused memory on last row when rowBytesAsPixels() exceeds width(). Returns SIZE_MAX if result does not fit in size_t. Returns zero if height() or width() is 0. Returns height() times rowBytes() if colorType() is kUnknown_ColorType.

Returns:

size in bytes of image buffer

Pixmap.computeIsOpaque(self: skia.Pixmap) → bool

Returns true if all pixels are opaque.

ColorType determines how pixels are encoded, and whether pixel describes alpha. Returns true for ColorType without alpha in each pixel; for other ColorType, returns true if all pixels have alpha values equivalent to 1.0 or greater.

For ColorType kRGB_565_ColorType or kGray_8_ColorType: always returns true. For ColorType kAlpha_8_ColorType, kBGRA_8888_ColorType, kRGBA_8888_ColorType: returns true if all pixel alpha values are 255. For ColorType kARGB_4444_ColorType: returns true if all pixel alpha values are 15. For kRGBA_F16_ColorType: returns true if all pixel alpha values are 1.0 or greater.

Returns false for kUnknown_ColorType.

Returns:

true if all pixels have opaque values or ColorType is opaque

Pixmap.dimensions(self: skia.Pixmap) → skia.ISize

Return the dimensions of the pixmap (from its ImageInfo)

Pixmap.erase(self: skia.Pixmap, color: skia.Color4f, subset: skia.IRect = None) → bool

Writes color to pixels bounded by subset; returns true on success.

if subset is nullptr, writes colors pixels inside bounds(). Returns false if colorType() is kUnknown_ColorType, if subset is not nullptr and does not intersect bounds(), or if subset is nullptr and bounds() is empty.

Parameters:

• color – sRGB unpremultiplied color to write

• subset – bounding integer Rect of pixels to write; may be nullptr

Returns:

true if pixels are changed

Pixmap.extractSubset(self: skia.Pixmap, subset: skia.Pixmap, area: skia.IRect) → bool

Sets subset width, height, pixel address to intersection of Pixmap with area, if intersection is not empty; and return true.

Otherwise, leave subset unchanged and return false.

Failing to read the return value generates a compile time warning.

Parameters:

• subset (skia.Pixmap) – storage for width, height, pixel address of intersection

• area (skia.IRect) – bounds to intersect with Pixmap

Returns:

true if intersection of Pixmap and area is not empty

Pixmap.getAlphaf(self: skia.Pixmap, x: int, y: int) → float

Look up the pixel at (x,y) and return its alpha component, normalized to [0..1].

This is roughly equivalent to GetColorA`( :py:meth:`getColor() ), but can be more efficent (and more precise if the pixels store more than 8 bits per component).

Parameters:

• x (int) – column index, zero or greater, and less than width()

• y (int) – row index, zero or greater, and less than height()

Returns:

alpha converted to normalized float

Pixmap.getColor(self: skia.Pixmap, x: int, y: int) → int

Returns pixel at (x, y) as unpremultiplied color.

Returns black with alpha if ColorType is kAlpha_8_ColorType.

Input is not validated: out of bounds values of x or y trigger an assert() if built with SK_DEBUG defined; and returns undefined values or may crash if SK_RELEASE is defined. Fails if ColorType is kUnknown_ColorType or pixel address is nullptr.

ColorSpace in ImageInfo is ignored. Some color precision may be lost in the conversion to unpremultiplied color; original pixel data may have additional precision.

Parameters:

• x (int) – column index, zero or greater, and less than width()

• y (int) – row index, zero or greater, and less than height()

Returns:

pixel converted to unpremultiplied color

Pixmap.height(self: skia.Pixmap) → int

Returns pixel row count.

Returns:

pixel height in SkImageInfo

Pixmap.info(self: skia.Pixmap) → skia.ImageInfo

Returns width, height, AlphaType, ColorType, and ColorSpace.

Returns:

reference to ImageInfo

Pixmap.isOpaque(self: skia.Pixmap) → bool

Returns true if AlphaType is kOpaque_AlphaType.

Does not check if ColorType allows alpha, or if any pixel value has transparency.

Returns:

true if ImageInfo has opaque AlphaType

Pixmap.readPixels(*args, **kwargs)

Overloaded function.

1. readPixels(self: skia.Pixmap, dstInfo: skia.ImageInfo, dstPixels: Buffer, dstRowBytes: int = 0, srcX: int = 0, srcY: int = 0) -> bool

   Copies Rect of pixels to dstPixels.

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

   dstInfo specifies width, height, ColorType, AlphaType, and ColorSpace of destination. dstRowBytes specifies the gap from one destination row to the next. Returns true if pixels are copied. Returns false if dstInfo address equals nullptr, or dstRowBytes is less than dstInfo.minRowBytes().

   Pixels are copied only if pixel conversion is possible. If Pixmap ColorType is kGray_8_ColorType, or kAlpha_8_ColorType; dstInfo.colorType must match. If Pixmap ColorType is kGray_8_ColorType, dstInfo.colorSpace must match. If Pixmap AlphaType is kOpaque_AlphaType, dstInfo.alphaType must match. If Pixmap ColorSpace 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) >= Pixmap width(), or if abs(srcY) >= Pixmap height().

   dstInfo:

   destination width, height, ColorType, AlphaType, ColorSpace

   dstPixels:

   destination pixel storage

   dstRowBytes:

   destination row length

   srcX:

   column index whose absolute value is less than width()

   srcY:

   row index whose absolute value is less than height()

   return:

   true if pixels are copied to dstPixels

2. readPixels(self: skia.Pixmap, dst: skia.Pixmap, srcX: int = 0, srcY: int = 0) -> bool

   Copies Rect of pixels to dst.

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

   dstInfo specifies width, height, ColorType, AlphaType, and ColorSpace of destination. dstRowBytes specifies the gap from one destination row to the next. Returns true if pixels are copied. Returns false if dstInfo address equals nullptr, or dstRowBytes is less than dstInfo.minRowBytes().

   Pixels are copied only if pixel conversion is possible. If Pixmap ColorType is kGray_8_ColorType, or kAlpha_8_ColorType; dstInfo.colorType must match. If Pixmap ColorType is kGray_8_ColorType, dstInfo.colorSpace must match. If Pixmap AlphaType is kOpaque_AlphaType, dstInfo.alphaType must match. If Pixmap ColorSpace 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) >= Pixmap width(), or if abs(srcY) >= Pixmap height().

   dst:

   ImageInfo and pixel address to write to

   srcX:

   column index whose absolute value is less than width()

   srcY:

   row index whose absolute value is less than height()

   return:

   true if pixels are copied to dst

Pixmap.refColorSpace(self: skia.Pixmap) → skia.ColorSpace

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

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.

Returns:

ColorSpace in ImageInfo wrapped in a smart pointer

Pixmap.reset(*args, **kwargs)

Overloaded function.

1. reset(self: skia.Pixmap) -> None

   Sets width, height, row bytes to zero; pixel address to nullptr; ColorType to kUnknown_ColorType; and AlphaType to kUnknown_AlphaType.

   The prior pixels are unaffected; it is up to the caller to release pixels memory if desired.

2. reset(self: skia.Pixmap, info: skia.ImageInfo, data: object, rowBytes: int) -> None

   Sets width, height, AlphaType, and ColorType from info.

   Sets pixel address from data, which may be nullptr. Sets row bytes from rowBytes, which should be info.width() times info.bytesPerPixel(), or larger.

   Does not check data. Asserts if built with SK_DEBUG defined and if rowBytes is too small to hold one row of pixels.

   The memory lifetime pixels are managed by the caller. When Pixmap goes out of scope, data is unaffected.

   param skia.ImageInfo info:

   width, height, AlphaType, ColorType of ImageInfo

   param Union[bytes,bytearray,memoryview] data:

   pointer to pixels allocated by caller; may be nullptr

   param int rowBytes:

   size of one row of data; width times pixel size, or larger

Pixmap.rowBytes(self: skia.Pixmap) → int

Returns row bytes, the interval from one pixel row to the next.

Row bytes is at least as large as: width() * info().bytesPerPixel().

Returns zero if colorType() is kUnknown_ColorType. It is up to the Bitmap creator to ensure that row bytes is a useful value.

Returns:

byte length of pixel row

Pixmap.rowBytesAsPixels(self: skia.Pixmap) → int

Returns number of pixels that fit on row.

Should be greater than or equal to width().

Returns:

maximum pixels per row

Pixmap.scalePixels(self: skia.Pixmap, dst: skia.Pixmap, samplingOptions: skia.SamplingOptions = skia.SamplingOptions()) → bool

Copies Pixmap 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 Pixmap ColorType is kGray_8_ColorType, or kAlpha_8_ColorType; dst.colorType() must match. If Pixmap ColorType is kGray_8_ColorType, dst.colorSpace() must match. If Pixmap AlphaType is kOpaque_AlphaType, dst.alphaType() must match. If Pixmap ColorSpace is nullptr, dst.colorSpace() must match. Returns false if pixel conversion is not possible.

Returns false if Pixmap width() or height() is zero or negative.

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.

Parameters:

• dst (skia.Pixmap) – destination Pixmap: ImageInfo, pixels, row bytes

• options (skia.SamplingOptions) – sampling options

Returns:

true if pixels are scaled to fit dst

Pixmap.setColorSpace(self: skia.Pixmap, colorSpace: skia.ColorSpace) → None

Changes ColorSpace in ImageInfo; preserves width, height, AlphaType, and ColorType in Image, and leaves pixel address and row bytes unchanged.

ColorSpace reference count is incremented.

Parameters:

colorSpace (skia.ColorSpace) – ColorSpace moved to ImageInfo

Pixmap.shiftPerPixel(self: skia.Pixmap) → int

Returns bit shift converting row bytes to row pixels.

Returns zero for kUnknown_ColorType.

Returns:

one of: 0, 1, 2, 3; left shift to convert pixels to bytes

Pixmap.tobytes(self: skia.Pixmap) → object

Pixmap.width(self: skia.Pixmap) → int

Returns pixel count in each pixel row.

Should be equal or less than: rowBytes() / info().bytesPerPixel().

Returns:

pixel width in ImageInfo

Pixmap.writable_addr(self: skia.Pixmap) → memoryview

Returns writable base pixel address.

Returns:

writable generic base pointer to pixels

Return type:

memoryview