S or /
skia canvas

SourceClass Canvas

from skia import Canvas
class Canvas:

Canvas provides an interface for drawing, and how the drawing is clipped and transformed. Canvas contains a stack of Matrix and clip values.

Canvas and Paint together provide the state to draw into Surface or Device. Each Canvas draw call transforms the geometry of the object by the concatenation of all Matrix values in the stack. The transformed geometry is clipped by the intersection of all of clip values in the stack. The Canvas draw calls use Paint to supply drawing state such as color, skia.Typeface, text size, stroke width, Shader and so on.

To draw to a pixel-based destination, create raster surface or GPU surface. Request Canvas from Surface to obtain the interface to draw. Canvas generated by raster surface draws to memory visible to the CPU. Canvas generated by GPU surface uses Vulkan or OpenGL to draw to the GPU.

To draw to a document, obtain Canvas from SVG canvas, document PDF, or skia.PictureRecorder. skia.Document based Canvas and other Canvas subclasses reference Device describing the destination.

Canvas can be constructed to draw to Bitmap without first creating raster surface. This approach may be deprecated in the future.

Constants§

ClipOp: Final[type]§
PointMode: Final[type]§

Properties§

@property def height(self, /) -> float |None§
@property def paint(self, /) -> Paint§
@paint.setter def paint(self, /, paint: Paint) -> None§
@property def rect(self, /) -> Rect |None§
@property def width(self, /) -> float |None§
@property def x(self, /) -> float |None§
@property def y(self, /) -> float |None§

Methods§

Sourcedef clear(self, /, color: Any) -> None§

Fills clip with color color using BlendMode.SRC. This has the effect of replacing all pixels contained by clip with color.

  • color Color4f representing unpremultiplied color.
Sourcedef clip_path(self, /, path: Path, op: ClipOp |None = None) -> None§

Replaces clip with the intersection or difference of clip and path, with an aliased or anti-aliased clip edge. skia.PathFillType determines if path describes the area inside or outside its contours; and if path contour overlaps itself or another path contour, whether the overlaps form part of the area. path is transformed by Matrix before it is combined with clip.

  • path Path to combine with clip
  • op ClipOp to apply to clip

Example (C++): https://fiddle.skia.org/c/@Canvas_clipPath

Sourcedef clip_rect(self, /, rect: Any, op: ClipOp |None = None) -> None§

Replaces clip with the intersection or difference of clip and rect, with an aliased or anti-aliased clip edge. rect is transformed by Matrix before it is combined with clip.

  • rect Rect to combine with clip
  • op ClipOp to apply to clip

Example (C++): https://fiddle.skia.org/c/@Canvas_clipRect

Sourcedef clip_rrect(self, /, rrect: RoundRect, op: ClipOp |None = None) -> None§

Replaces clip with the intersection or difference of clip and rrect, with an aliased or anti-aliased clip edge. rrect is transformed by Matrix before it is combined with clip.

Example (C++): https://fiddle.skia.org/c/@Canvas_clipRRect

Sourcedef concat(self, /, matrix: Matrix) -> None§

Replaces Matrix with matrix premultiplied with existing Matrix.

This has the effect of transforming the drawn geometry by matrix, before transforming the result with existing Matrix.

  • matrix matrix to premultiply with existing Matrix

Example (C++): https://fiddle.skia.org/c/@Canvas_concat

def contains(self, /, x: float, y: float) -> bool§
Sourcedef discard(self, /) -> None§

Makes Canvas contents undefined. Subsequent calls that read Canvas pixels, such as drawing with BlendMode, return undefined results. discard() does not change clip or Matrix.

discard() may do nothing, depending on the implementation of Surface or Device that created Canvas.

discard() allows optimized performance on subsequent draws by removing cached data associated with Surface or Device. It is not necessary to call discard() once done with Canvas; any cached data is deleted when owning Surface or Device is deleted.

Sourcedef draw_circle(self, /, cx: float, cy: float, rad: float, paint: Paint |None = None) -> None§

Draws circle at center with radius using clip, Matrix, and Paint paint. If radius is zero or less, nothing is drawn. In paint: skia.PaintStyle determines if circle is stroked or filled; if stroked, Paint stroke width describes the line thickness.

  • (cx, cy) circle center
  • rad half the diameter of circle
  • paint Paint stroke or fill, blend, color, and so on, used to draw

Example (C++): https://fiddle.skia.org/c/@Canvas_drawCircle

Sourcedef draw_color(self, /, color: Any, mode: BlendMode |None = None) -> None§

Fills clip with color color. mode determines how ARGB is combined with destination.

  • color Color4f representing unpremultiplied color.
  • mode BlendMode used to combine source color and destination

Example (C++): https://fiddle.skia.org/c/@Canvas_drawColor

Sourcedef draw_image(self, /, image: Image, x: float, y: float, paint: Paint |None = None, sampling: SamplingOptions |None = None) -> None§
Sourcedef draw_image_rect(self, /, image: Image, src: Any, dst: Any, paint: Paint |None = None, sampling: SamplingOptions |None = None) -> None§
Sourcedef draw_line(self, /, x0: float, y0: float, x1: float, y1: float, paint: Paint |None = None) -> None§

Draws line segment from (x0, y0) to (x1, y1) using clip, Matrix, and Paint paint. In paint: Paint stroke width describes the line thickness; skia.StrokeCap draws the end rounded or square; skia.PaintStyle is ignored, as if were set to skia.PaintStyle.Stroke.

  • (x0, y0) start of line segment
  • (x1, y1) end of line segment
  • paint stroke, blend, color, and so on, used to draw

Example (C++): https://fiddle.skia.org/c/@Canvas_drawLine

Sourcedef draw_oval(self, /, rect: Any, paint: Paint |None = None) -> None§

Draws oval oval using clip, Matrix, and Paint. In paint: skia.PaintStyle determines if oval is stroked or filled; if stroked, Paint stroke width describes the line thickness.

  • rect Rect bounds of oval
  • paint Paint stroke or fill, blend, color, and so on, used to draw

Example (C++): https://fiddle.skia.org/c/@Canvas_drawOval

Sourcedef draw_paint(self, /, paint: Paint |None = None) -> None§

Fills clip with Paint paint. Paint components, Shader, skia.ColorFilter, ImageFilter, and BlendMode affect drawing; skia.MaskFilter and skia.PathEffect in paint are ignored.

  • paint graphics state used to fill Canvas

Example (C++): https://fiddle.skia.org/c/@Canvas_drawPaint

Sourcedef draw_path(self, /, path: Path, paint: Paint |None = None) -> None§

Draws Path path using clip, Matrix, and Paint paint. Path contains an array of path contour, each of which may be open or closed.

In paint: skia.PaintStyle determines if RoundRect is stroked or filled: if filled, skia.PathFillType determines whether path contour describes inside or outside of fill; if stroked, Paint stroke width describes the line thickness, skia.StrokeCap describes line ends, and skia.StrokeJoin describes how corners are drawn.

  • path Path to draw
  • paint stroke, blend, color, and so on, used to draw

Example (C++): https://fiddle.skia.org/c/@Canvas_drawPath

Sourcedef draw_point(self, /, x: float, y: float, paint: Paint |None = None) -> None§

Draws point (x, y) using clip, Matrix and Paint paint.

The shape of point drawn depends on paint skia.StrokeCap. If paint is set to skia.StrokeCap.ROUND, draw a circle of diameter Paint stroke width. If paint is set to skia.StrokeCap.SQUARE or skia.StrokeCap.BUTT, draw a square of width and height Paint stroke width. skia.PaintStyle is ignored, as if were set to skia.PaintStyle.Stroke.

  • (x, y) top-left edge of circle or square
  • paint stroke, blend, color, and so on, used to draw

Example (C++): https://fiddle.skia.org/c/@Canvas_drawPoint

Sourcedef draw_points(self, /, mode: PointMode, points: Sequence[Any], paint: Paint |None = None) -> None§

Draws points using clip, Matrix and Paint pain. if the number of points is less than one, has no effect. mode may be one of: PointMode.POINTS, PointMode.LINES, or PointMode.POLYGON

If mode is PointMode.POINTS, the shape of point drawn depends on paint skia.StrokeCap. If paint is set to skia.StrokeCap.ROUND, each point draws a circle of diameter Paint stroke width. If paint is set to skia.StrokeCap.SQUARE or skia.StrokeCap.BUTT, each point draws a square of width and height Paint stroke width.

If mode is PointMode.LINES, each pair of points draws a line segment. One line is drawn for every two points; each point is used once. If count is odd, the final point is ignored.

If mode is PointMode.POLYGON, each adjacent pair of points draws a line segment. count minus one lines are drawn; the first and last point are used once.

Each line segment respects paint skia.StrokeCap and Paint stroke width. skia.PaintStyle is ignored, as if were set to skia.PaintStyle.Stroke.

Always draws each element one at a time; is not affected by skia.StrokeJoin, and unlike skia.Canvas.draw_path(), does not create a mask from all points and lines before drawing.

  • mode whether pts draws points or lines
  • points array of points to draw
  • paint stroke, blend, color, and so on, used to draw

Example (C++): https://fiddle.skia.org/c/@Canvas_drawPoints

Sourcedef draw_rect(self, /, rect: Any, paint: Paint |None = None) -> None§

Draws Rect rect using clip, Matrix, and Paint paint. In paint: skia.PaintStyle determines if rectangle is stroked or filled; if stroked, Paint stroke width describes the line thickness, and skia.StrokeJoin draws the corners rounded or square.

  • rect rectangle to draw
  • paint stroke or fill, blend, color, and so on, used to draw

Example (C++): https://fiddle.skia.org/c/@Canvas_drawRect

Sourcedef draw_round_rect(self, /, rect: Any, rx: float, ry: float, paint: Paint |None = None) -> None§

Draws RoundRect bounded by Rect rect, with corner radii (rx, ry) using clip, Matrix, and Paint paint.

In paint: skia.PaintStyle determines if RoundRect is stroked or filled; if stroked, Paint stroke width describes the line thickness. If rx or ry are less than zero, they are treated as if they are zero. If rx plus ry exceeds rect width or rect height, radii are scaled down to fit. If rx and ry are zero, RoundRect is drawn as Rect and if stroked is affected by skia.StrokeJoin.

  • rect Rect bounds of RoundRect to draw
  • rx axis length on x-axis of oval describing rounded corners
  • ry axis length on y-axis of oval describing rounded corners
  • paint stroke, blend, color, and so on, used to draw

Example (C++): https://fiddle.skia.org/c/@Canvas_drawRoundRect

Sourcedef draw_rrect(self, /, rrect: RoundRect, paint: Paint |None = None) -> None§

Draws RoundRect rrect using clip, Matrix, and Paint paint. In paint: skia.PaintStyle determines if rrect is stroked or filled; if stroked, Paint stroke width describes the line thickness.

rrect may represent a rectangle, circle, oval, uniformly rounded rectangle, or may have any combination of positive non-square radii for the four corners.

  • rrect RoundRect with up to eight corner radii to draw
  • paint Paint stroke or fill, blend, color, and so on, used to draw

Example (C++): https://fiddle.skia.org/c/@Canvas_drawRRect

def draw_text(self, /, text: str, x: float, y: float, paint: Paint |None = None) -> None§
def flush(self, /) -> None§
Source@classmethod def from_bitmap(cls, /, _bitmap: Bitmap) -> Canvas§

Constructs a canvas that draws into bitmap. Use props to match the device characteristics, like LCD striping.

bitmap is copied so that subsequently editing bitmap will not affect constructed Canvas.

Returns Canvas that can be used to draw into bitmap

Example (C++): https://fiddle.skia.org/c/@Canvas_copy_const_SkBitmap Example (C++): https://fiddle.skia.org/c/@Canvas_const_SkBitmap_const_SkSurfaceProps

def get_save_count(self, /) -> int§
def get_total_matrix(self, /) -> Matrix4§
def quick_reject(self, /, rect: Any) -> bool§
Sourcedef reset_matrix(self, /) -> None§

Sets Matrix to the identity matrix. Any prior matrix state is overwritten.

Example (C++): https://fiddle.skia.org/c/@Canvas_resetMatrix

Sourcedef restore(self, /) -> None§

Removes changes to Matrix and clip since Canvas state was last saved. The state is removed from the stack.

Does nothing if the stack is empty.

Example (C++): https://fiddle.skia.org/c/@AutoCanvasRestore_restore Example (C++): https://fiddle.skia.org/c/@Canvas_restore

Sourcedef restore_to_count(self, /, count: int) -> None§

Restores state to Matrix and clip values when skia.Canvas.save(), skia.Canvas.save_layer(), or skia.Canvas.save_layer_alpha() returned count.

Does nothing if count is greater than state stack count. Restores state to initial values if count is less than or equal to one.

  • count depth of state stack to restore

Example (C++): https://fiddle.skia.org/c/@Canvas_restoreToCount

def rotate_degrees(self, /, degrees: float) -> None§
def rotate_radians(self, /, radians: float) -> None§
Sourcedef save(self, /) -> int§

Saves Matrix and clip. Calling skia.Canvas.restore() discards changes to Matrix and clip, restoring the Matrix and clip to their state when skia.Canvas.save() was called.

Matrix may be changed by skia.Canvas.translate(), skia.Canvas.scale(), skia.Canvas.rotate(), skia.Canvas.skew(), skia.Canvas.concat(), skia.Canvas.set_matrix(), and skia.Canvas.reset_matrix(). Clip may be changed by skia.Canvas.clip_rect(), skia.Canvas.clip_rrect(), skia.Canvas.clip_path(), skia.Canvas.clip_region().

Saved Canvas state is put on a stack; multiple calls to skia.Canvas.save() should be balance by an equal number of calls to skia.Canvas.restore().

Call skia.Canvas.restore_to_count() with result to restore this and subsequent saves.

Returns depth of saved stack

Example (C++): https://fiddle.skia.org/c/@Canvas_save

def saved(self, /) -> Any§
Sourcedef scale(self, /, sx: float, sy: float) -> None§

Scales Matrix by sx on the x-axis and sy on the y-axis.

Mathematically, replaces Matrix with a scale matrix premultiplied with Matrix.

This has the effect of scaling the drawing by (sx, sy) before transforming the result with Matrix.

  • sx amount to scale on x-axis
  • sy amount to scale on y-axis

Example (C++): https://fiddle.skia.org/c/@Canvas_scale

Sourcedef set_matrix(self, /, matrix: Matrix4) -> None§

Replaces Matrix with matrix. Unlike skia.Canvas.concat(), any prior matrix state is overwritten.

  • matrix matrix to copy, replacing existing Matrix

Example (C++): https://fiddle.skia.org/c/@Canvas_setMatrix

Sourcedef skew(self, /, sx: float, sy: float) -> None§

Skews Matrix by sx on the x-axis and sy on the y-axis. A positive value of sx skews the drawing right as y-axis values increase; a positive value of sy skews the drawing down as x-axis values increase.

Mathematically, replaces Matrix with a skew matrix premultiplied with Matrix.

This has the effect of skewing the drawing by (sx, sy) before transforming the result with Matrix.

  • sx amount to skew on x-axis
  • sy amount to skew on y-axis

Example (C++): https://fiddle.skia.org/c/@Canvas_skew

Sourcedef translate(self, /, dx: float, dy: float) -> None§

Translates Matrix by (dx, dy).

Mathematically, replaces Matrix with a translation matrix premultiplied with Matrix.

This has the effect of moving the drawing by (d.x, d.y) before transforming the result with Matrix.

  • (dx, dy) distance to translate

Example (C++): https://fiddle.skia.org/c/@Canvas_translate