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