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__`	Returns a placeholder `Picture`.
`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

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, mode: skia.FilterMode, 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.