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__

__init__(*args, **kwargs) 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)

__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 = <ColorType.kRGBA_8888_ColorType: 4>, alphaType: skia.AlphaType = <AlphaType.kUnpremul_AlphaType: 3>, 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, filterQuality: skia.FilterQuality = <FilterQuality.kMedium_FilterQuality: 2>) 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
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