Picture

class Picture

Picture records drawing commands made to Canvas.

The command stream may be played in whole or in part at a later time.

Picture is an abstract class. Picture may be generated by PictureRecorder or Drawable, or from Picture previously saved to Data or Stream.

Picture may contain any Canvas drawing command, as well as one or more Canvas matrix or Canvas clip. Picture has a cull Rect, which is used as a bounding box hint. To limit Picture bounds, use Canvas clip when recording or drawing Picture.

Example:

recorder = skia.PictureRecorder()
canvas = recorder.beginRecording(skia.Rect(100, 100))
canvas.clear(0xFFFFFFFF)
canvas.drawLine(0, 0, 100, 100, skia.Paint())
picture = recorder.finishRecordingAsPicture()

Methods

MakeFromData

Recreates Picture that was serialized into data.

MakeFromStream

Recreates Picture that was serialized into a stream.

MakePlaceholder

Returns a placeholder Picture.

__init__

__init__(self: skia.Picture, cull: skia.Rect) -> None

approximateBytesUsed

Returns the approximate byte size of Picture.

approximateOpCount

Returns the approximate number of operations in Picture.

cullRect

Returns cull Rect for this picture, passed in when Picture was created.

makeShader

Return a new shader that will draw with this picture.

playback

Replays the drawing commands on the specified canvas.

ref

Increment the reference count.

serialize

Returns storage containing Data describing Picture.

unique

May return true if the caller is the only owner.

uniqueID

Returns a non-zero value unique among Picture in Skia process.

unref

Decrement the reference count.

Methods

static Picture.MakeFromData(data: skia.Data) skia.Picture

Recreates Picture that was serialized into data.

Returns constructed Picture if successful. Fails if data does not permit constructing valid Picture.

Parameters

data (skia.Data) – container for serial data

Returns

Picture constructed from data

Raise

ValueError

static Picture.MakeFromStream(stream: skia.Stream) skia.Picture

Recreates Picture that was serialized into a stream.

Returns constructed Picture if successful; otherwise, returns nullptr. Fails if data does not permit constructing valid Picture.

Parameters

stream – container for serial data

Returns

Picture constructed from stream data

static Picture.MakePlaceholder(cull: skia.Rect) skia.Picture

Returns a placeholder Picture.

Result does not draw, and contains only cull Rect, a hint of its bounds. Result is immutable; it cannot be changed later. Result identifier is unique.

Returned placeholder can be intercepted during playback to insert other commands into Canvas draw stream.

Parameters

cull (skia.Rect) – placeholder dimensions

Returns

placeholder with unique identifier

Picture.__init__(self: skia.Picture, cull: skia.Rect) None

__init__(self: skia.Picture, cull: skia.Rect) -> None

Returns a placeholder Picture.

Result does not draw, and contains only cull Rect, a hint of its bounds. Result is immutable; it cannot be changed later. Result identifier is unique.

Returned placeholder can be intercepted during playback to insert other commands into Canvas draw stream.

Parameters

cull (skia.Rect) – placeholder dimensions

Returns

placeholder with unique identifier

Picture.approximateBytesUsed(self: skia.Picture) int

Returns the approximate byte size of Picture.

Does not include large objects referenced by Picture.

Returns

approximate size

Picture.approximateOpCount(self: skia.Picture, nested: bool = False) int

Returns the approximate number of operations in Picture.

Returned value may be greater or less than the number of Canvas calls recorded: some calls may be recorded as more than one operation, other calls may be optimized away.

Returns

approximate operation count

Picture.cullRect(self: skia.Picture) skia.Rect

Returns cull Rect for this picture, passed in when Picture was created.

Returned Rect does not specify clipping Rect for Picture; cull is hint of Picture bounds.

Picture is free to discard recorded drawing commands that fall outside cull.

Returns

bounds passed when Picture was created

Picture.makeShader(self: skia.Picture, tmx: skia.TileMode, tmy: skia.TileMode, localMatrix: skia.Matrix = None, tile: skia.Rect = None) skia.Shader

Return a new shader that will draw with this picture.

Parameters
  • tmx (skia.TileMode) – The tiling mode to use when sampling in the x-direction.

  • tmy (skia.TileMode) – The tiling mode to use when sampling in the y-direction.

  • localMatrix (skia.Matrix) – Optional matrix used when sampling

  • tile (skia.Rect) – The tile rectangle in picture coordinates: this represents the subset (or superset) of the picture used when building a tile. It is not affected by localMatrix and does not imply scaling (only translation and cropping). If null, the tile rect is considered equal to the picture bounds.

Returns

Returns a new shader object. Note: this function never returns null.

Picture.playback(self: skia.Picture, canvas: SkCanvas) None

Replays the drawing commands on the specified canvas.

In the case that the commands are recorded, each command in the Picture is sent separately to canvas.

To add a single command to draw Picture to recording canvas, call Canvas.drawPicture() instead.

Parameters
  • canvas (skia.Canvas) – receiver of drawing commands

  • callback – allows interruption of playback

Picture.ref(self: skia.RefCntBase) None

Increment the reference count.

Must be balanced by a call to unref().

Picture.serialize(self: skia.Picture) skia.Data

Returns storage containing Data describing Picture.

Returns

storage containing serialized Picture

Picture.unique(self: skia.RefCntBase) bool

May return true if the caller is the only owner.

Ensures that all previous owner’s actions are complete.

Picture.uniqueID(self: skia.Picture) int

Returns a non-zero value unique among Picture in Skia process.

Returns

identifier for Picture

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