SKCanvas Class
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Encapsulates all of the state about drawing into a device (bitmap or surface).
public class SKCanvas : SkiaSharp.SKObject- Inheritance
- Derived
Examples
var info = new SKImageInfo(640, 480);
using (var surface = SKSurface.Create(info)) {
SKCanvas canvas = surface.Canvas;
canvas.Clear(SKColors.White);
// set up drawing tools
var paint = new SKPaint {
IsAntialias = true,
Color = new SKColor(0x2c, 0x3e, 0x50),
StrokeCap = SKStrokeCap.Round
};
// create the Xamagon path
var path = new SKPath();
path.MoveTo(71.4311121f, 56f);
path.CubicTo(68.6763107f, 56.0058575f, 65.9796704f, 57.5737917f, 64.5928855f, 59.965729f);
path.LineTo(43.0238921f, 97.5342563f);
path.CubicTo(41.6587026f, 99.9325978f, 41.6587026f, 103.067402f, 43.0238921f, 105.465744f);
path.LineTo(64.5928855f, 143.034271f);
path.CubicTo(65.9798162f, 145.426228f, 68.6763107f, 146.994582f, 71.4311121f, 147f);
path.LineTo(114.568946f, 147f);
path.CubicTo(117.323748f, 146.994143f, 120.020241f, 145.426228f, 121.407172f, 143.034271f);
path.LineTo(142.976161f, 105.465744f);
path.CubicTo(144.34135f, 103.067402f, 144.341209f, 99.9325978f, 142.976161f, 97.5342563f);
path.LineTo(121.407172f, 59.965729f);
path.CubicTo(120.020241f, 57.5737917f, 117.323748f, 56.0054182f, 114.568946f, 56f);
path.LineTo(71.4311121f, 56f);
path.Close();
// draw the Xamagon path
canvas.DrawPath(path, paint);
}
Remarks
A canvas encapsulates all of the state about drawing into a device (bitmap or surface).
This includes a reference to the device itself, and a stack of matrix/clip values. For any given draw call (e.g. DrawRect), the geometry of the object being drawn is transformed by the concatenation of all the matrices in the stack. The transformed geometry is clipped by the intersection of all of the clips in the stack.
While the canvas holds the state of the drawing device, the state (style) of the object being drawn is held by the paint, which is provided as a parameter to each of the "Draw" methods. The paint holds attributes such as color, typeface, the text size, the stroke width, the shader (for example, gradients, patterns), etc.
The canvas is returned when accessing the SKSurface.Canvas property of a surface.
Construction
SkiaSharp has multiple backends which receive SKCanvas drawing commands, including:
- Raster Surface
- GPU Surface
- PDF Document
- XPS Document (experimental)
- SVG Canvas (experimental)
- Picture
- Null Canvas (for testing)
Constructing a Raster Surface
The raster backend draws to a block of memory. This memory can be managed by SkiaSharp or by the client.
The recommended way of creating a canvas for the Raster and Ganesh backends is to use a SKSurface, which is an object that manages the memory into which the canvas commands are drawn.
// define the surface properties
var info = new SKImageInfo(256, 256);
// construct a new surface
var surface = SKSurface.Create(info);
// get the canvas from the surface
var canvas = surface.Canvas;
// draw on the canvas ...
Alternatively, we could have specified the memory for the surface explicitly, instead of asking SkiaSharp to manage it.
// define the surface properties
var info = new SKImageInfo(256, 256);
// allocate memory
var memory = Marshal.AllocCoTaskMem(info.BytesSize);
// construct a surface around the existing memory
var surface = SKSurface.Create(info, memory, info.RowBytes);
// get the canvas from the surface
var canvas = surface.Canvas;
// draw on the canvas ...
Constructing a GPU Surface
GPU surfaces must have a GRContext object which manages the GPU context, and related caches for textures and fonts.
GRContext objects are matched one to one with OpenGL contexts or Vulkan devices. That is, all SKSurface instances that will be rendered to using the same OpenGL context or Vulkan device should share a GRContext.
SkiaSharp does not create an OpenGL context or a Vulkan device for you. In OpenGL mode it also assumes that the correct OpenGL context has been made current to the current thread when SkiaSharp calls are made.
// an OpenGL context must be created and set as current
// define the surface properties
var info = new SKImageInfo(256, 256);
// create the surface
var context = GRContext.CreateGl();
var surface = SKSurface.Create(context, false, info);
// get the canvas from the surface
var canvas = surface.Canvas;
// draw on the canvas ...
Constructing a PDF Document
The PDF backend uses SKDocument instead of SKSurface, since a document must include multiple pages.
// create the document
var stream = SKFileWStream.OpenStream("document.pdf");
var document = SKDocument.CreatePdf(stream);
// get the canvas from the page
var canvas = document.BeginPage(256, 256);
// draw on the canvas ...
// end the page and document
document.EndPage();
document.Close();
Constructing a XPS Document (experimental)
The XPS backend uses SKDocument instead of SKSurface, since a document must include multiple pages.
// create the document
var stream = SKFileWStream.OpenStream("document.xps");
var document = SKDocument.CreateXps(stream);
// get the canvas from the page
var canvas = document.BeginPage(256, 256);
// draw on the canvas ...
// end the page and document
document.EndPage();
document.Close();
Constructing a SVG Canvas (experimental)
The SVG backend uses SKSvgCanvas.
// create the canvas
var stream = SKFileWStream.OpenStream("image.svg");
var writer = new SKXmlStreamWriter(stream);
var canvas = SKSvgCanvas.Create(SKRect.Create(256, 256), writer);
// draw on the canvas ...
Constructing a Picture
The XPS backend uses SKPictureRecorder instead of SKSurface.
// create the picture recorder
var recorder = new SKPictureRecorder();
// get the canvas from the page
var canvas = recorder.BeginRecording(SKRect.Create(256, 256));
// draw on the canvas ...
// finish recording
var picture = recorder.EndRecording();
Constructing a Null Canvas (for testing)
The null canvas is a canvas that ignores all drawing commands and does nothing.
// create the dummy canvas
var canvas = new SKNoDrawCanvas(256, 256);
// draw on the canvas ...
Transformations
The canvas supports a number of 2D transformations. Unlike other 2D graphic systems like CoreGraphics or Cairo, SKCanvas extends the transformations to include perspectives.
You can use the Scale, Skew, Translate, RotateDegrees, RotateRadians to perform some of the most common 2D transformations.
For more control you can use the SetMatrix to set an arbitrary transformation using the SKMatrix and the Concat to concatenate an SKMatrix transformation to the current matrix in use.
The ResetMatrix can be used to reset the state of the matrix.
Drawing
The drawing operations can take a SKPaint parameter to affect their drawing. You use SKPaint objects to cache the style and color information to draw geometries, texts and bitmaps.
Clipping and State
It is possible to save the current transformations by calling the Save method which preserves the current transformation matrix, you can then alter the matrix and restore the previous state by using the Restore or RestoreToCount methods.
Additionally, it is possible to push a new state with SaveLayer which will make an offscreen copy of a region, and once the drawing is completed, calling the Restore() method which copies the offscreen bitmap into this canvas.
Constructors
| SKCanvas(SKBitmap) |
Creates a canvas with the specified bitmap to draw into. |
Properties
| DeviceClipBounds |
Gets the bounds of the current clip (in device coordinates). |
| Handle |
Gets or sets the handle to the underlying native object. (Inherited from SKObject) |
| IgnorePublicDispose |
Gets or sets a value indicating whether the call the public Dispose() should be no-op. (Inherited from SKNativeObject) |
| IsClipEmpty | |
| IsClipRect | |
| IsDisposed |
Gets or sets a value indicating whether the object has already been disposed. (Inherited from SKNativeObject) |
| LocalClipBounds |
Gets the bounds of the current clip (in local coordinates). |
| OwnsHandle |
Gets a value indicating whether this object should destroy the underlying native object. (Inherited from SKObject) |
| SaveCount |
Gets the number of matrix/clip states on the canvas' private stack. |
| TotalMatrix |
Gets the current matrix on the canvas. |
Methods
| Clear() |
Replaces all the pixels in the canvas' current clip with the Empty color. |
| Clear(SKColor) |
Replaces all the pixels in the canvas' current clip with the specified color. |
| Clear(SKColorF) | |
| ClipPath(SKPath, SKClipOperation, Boolean) |
Modify the current clip with the specified path. |
| ClipRect(SKRect, SKClipOperation, Boolean) |
Modify the current clip with the specified rectangle. |
| ClipRegion(SKRegion, SKClipOperation) |
Modify the current clip with the specified region. |
| ClipRoundRect(SKRoundRect, SKClipOperation, Boolean) |
Modify the current clip with the specified rounded rectangle. |
| Concat(SKMatrix) |
Pre-concatenates the provided transformation matrix with the current transformation matrix. |
| Discard() |
Makes the canvas contents undefined. |
| Dispose() |
Releases all resources used by this SKNativeObject. (Inherited from SKNativeObject) |
| Dispose(Boolean) |
Releases the unmanaged resources used by the SKCanvas and optionally releases the managed resources. |
| DisposeInternal() |
Triggers a dispose, ignoring the value of IgnorePublicDispose. (Inherited from SKNativeObject) |
| DisposeManaged() |
Implemented by derived SKObject types to destroy any managed objects. (Inherited from SKObject) |
| DisposeNative() |
Implemented by derived SKObject types to destroy any native objects. |
| DisposeNative() |
Implemented by derived SKObject types to destroy any native objects. (Inherited from SKObject) |
| DisposeUnownedManaged() | (Inherited from SKObject) |
| DrawAnnotation(SKRect, String, SKData) |
Send an key/value pair "annotation" to the canvas. |
| DrawArc(SKRect, Single, Single, Boolean, SKPaint) | |
| DrawAtlas(SKImage, SKRect[], SKRotationScaleMatrix[], SKColor[], SKBlendMode, SKPaint) | |
| DrawAtlas(SKImage, SKRect[], SKRotationScaleMatrix[], SKColor[], SKBlendMode, SKRect, SKPaint) | |
| DrawAtlas(SKImage, SKRect[], SKRotationScaleMatrix[], SKPaint) | |
| DrawBitmap(SKBitmap, Single, Single, SKPaint) |
Draws a bitmap on the canvas. |
| DrawBitmap(SKBitmap, SKPoint, SKPaint) |
Draws a bitmap on the canvas. |
| DrawBitmap(SKBitmap, SKRect, SKPaint) |
Draws a bitmap on the canvas. |
| DrawBitmap(SKBitmap, SKRect, SKRect, SKPaint) |
Draws a bitmap on the canvas. |
| DrawBitmapLattice(SKBitmap, Int32[], Int32[], SKRect, SKPaint) |
Draws the bitmap, stretched or shrunk differentially to fit into the destination rectangle. |
| DrawBitmapLattice(SKBitmap, SKLattice, SKRect, SKPaint) |
Draws the bitmap, stretched or shrunk differentially to fit into the destination rectangle. |
| DrawBitmapNinePatch(SKBitmap, SKRectI, SKRect, SKPaint) |
Draws the bitmap, stretched or shrunk differentially to fit into the destination rectangle. |
| DrawCircle(Single, Single, Single, SKPaint) |
Draws a circle on the canvas. |
| DrawCircle(SKPoint, Single, SKPaint) |
Draws a circle on the canvas. |
| DrawColor(SKColor, SKBlendMode) |
Fills the current clipping area with the specified color using the specified color and blend mode. |
| DrawColor(SKColorF, SKBlendMode) | |
| DrawDrawable(SKDrawable, Single, Single) |
Draws a drawable on the canvas. |
| DrawDrawable(SKDrawable, SKMatrix) |
Draws a drawable on the canvas. |
| DrawDrawable(SKDrawable, SKPoint) |
Draws a drawable on the canvas. |
| DrawImage(SKImage, Single, Single, SKPaint) |
Draws an image on the canvas. |
| DrawImage(SKImage, SKPoint, SKPaint) |
Draws an image on the canvas. |
| DrawImage(SKImage, SKRect, SKPaint) |
Draws an image on the canvas. |
| DrawImage(SKImage, SKRect, SKRect, SKPaint) |
Draws an image on the canvas. |
| DrawImageLattice(SKImage, Int32[], Int32[], SKRect, SKPaint) |
Draws the image, stretched or shrunk differentially to fit into the destination rectangle. |
| DrawImageLattice(SKImage, SKLattice, SKRect, SKPaint) |
Draws the image, stretched or shrunk differentially to fit into the destination rectangle. |
| DrawImageNinePatch(SKImage, SKRectI, SKRect, SKPaint) |
Draws the image, stretched or shrunk differentially to fit into the destination rectangle. |
| DrawLine(Single, Single, Single, Single, SKPaint) |
Draws a line on the canvas. |
| DrawLine(SKPoint, SKPoint, SKPaint) |
Draws a line on the canvas. |
| DrawLinkDestinationAnnotation(SKRect, SKData) |
Annotates the canvas by making the specified rectangle link to a named destination (see DrawNamedDestinationAnnotation(SKPoint, SKData)). |
| DrawLinkDestinationAnnotation(SKRect, String) |
Annotates the canvas by making the specified rectangle link to a named destination (see DrawNamedDestinationAnnotation(SKPoint, String)). |
| DrawNamedDestinationAnnotation(SKPoint, SKData) |
Annotates the canvas by associating a name with the specified point (see DrawLinkDestinationAnnotation(SKRect, SKData)). |
| DrawNamedDestinationAnnotation(SKPoint, String) |
Annotates the canvas by associating a name with the specified point (see DrawLinkDestinationAnnotation(SKRect, String)). |
| DrawOval(Single, Single, Single, Single, SKPaint) |
Draws an oval on the canvas. |
| DrawOval(SKPoint, SKSize, SKPaint) |
Draws an oval on the canvas. |
| DrawOval(SKRect, SKPaint) |
Draws an oval on the canvas. |
| DrawPaint(SKPaint) |
Fills the current clipping path with the specified paint. |
| DrawPatch(SKPoint[], SKColor[], SKPoint[], SKBlendMode, SKPaint) | |
| DrawPatch(SKPoint[], SKColor[], SKPoint[], SKPaint) | |
| DrawPath(SKPath, SKPaint) |
Draws a path in the canvas. |
| DrawPicture(SKPicture, Single, Single, SKPaint) |
Draws a picture on the canvas. |
| DrawPicture(SKPicture, SKMatrix, SKPaint) |
Draws a picture on the canvas. |
| DrawPicture(SKPicture, SKPaint) |
Draws a picture on the canvas. |
| DrawPicture(SKPicture, SKPoint, SKPaint) |
Draws a picture on the canvas. |
| DrawPoint(Single, Single, SKColor) |
Draws a point in the canvas with the specified color. |
| DrawPoint(Single, Single, SKPaint) |
Draws a point in the canvas with the specified color. |
| DrawPoint(SKPoint, SKColor) |
Draws a point in the canvas with the specified color. |
| DrawPoint(SKPoint, SKPaint) |
Draws a point in the canvas with the specified color. |
| DrawPoints(SKPointMode, SKPoint[], SKPaint) |
Draws an array of points, lines or a polygon in the canvas, one at a time. |
| DrawPositionedText(Byte[], SKPoint[], SKPaint) |
Obsolete.
Draws glyphs of the text at specified locations on the canvas. |
| DrawPositionedText(IntPtr, Int32, SKPoint[], SKPaint) |
Obsolete.
Draws text from a UTF-8 buffer at specified locations on the canvas. |
| DrawPositionedText(String, SKPoint[], SKPaint) |
Obsolete.
Draws glyphs of the text at specified locations on the canvas. |
| DrawRect(Single, Single, Single, Single, SKPaint) |
Draws a rectangle in the canvas. |
| DrawRect(SKRect, SKPaint) |
Draws a rectangle in the canvas. |
| DrawRegion(SKRegion, SKPaint) |
Draws the outline of the specified region using the specified paint. |
| DrawRoundRect(Single, Single, Single, Single, Single, Single, SKPaint) |
Draws a rounded rectangle in the canvas. |
| DrawRoundRect(SKRect, Single, Single, SKPaint) |
Draws a rounded rectangle in the canvas. |
| DrawRoundRect(SKRect, SKSize, SKPaint) |
Draws a rounded rectangle in the canvas. |
| DrawRoundRect(SKRoundRect, SKPaint) |
Draws a rounded rectangle in the canvas. |
| DrawRoundRectDifference(SKRoundRect, SKRoundRect, SKPaint) | |
| DrawSurface(SKSurface, Single, Single, SKPaint) |
Draws a surface on the canvas. |
| DrawSurface(SKSurface, SKPoint, SKPaint) |
Draws a surface on the canvas. |
| DrawText(Byte[], Single, Single, SKPaint) |
Obsolete.
Draws text on the canvas at the specified coordinates. |
| DrawText(Byte[], SKPoint, SKPaint) |
Obsolete.
Draws text on the canvas at the specified coordinates. |
| DrawText(IntPtr, Int32, Single, Single, SKPaint) |
Obsolete.
Draws text encoded in a UTF-8 buffer on the canvas at the specified coordinates. |
| DrawText(IntPtr, Int32, SKPoint, SKPaint) |
Obsolete.
Draws text encoded in a UTF-8 buffer on the canvas at the specified coordinates. |
| DrawText(SKTextBlob, Single, Single, SKPaint) |
Draws a text blob on the canvas at the specified coordinates. |
| DrawText(String, Single, Single, SKFont, SKPaint) | |
| DrawText(String, Single, Single, SKPaint) |
Draws text on the canvas at the specified coordinates. |
| DrawText(String, SKPoint, SKPaint) |
Draws text on the canvas at the specified coordinates. |
| DrawTextOnPath(Byte[], SKPath, Single, Single, SKPaint) |
Obsolete.
Draws text on the canvas following a path. |
| DrawTextOnPath(Byte[], SKPath, SKPoint, SKPaint) |
Obsolete.
Draws text on the canvas following a path. |
| DrawTextOnPath(IntPtr, Int32, SKPath, Single, Single, SKPaint) |
Obsolete.
Draws text encoded in a UTF-8 buffer on the canvas following a path. |
| DrawTextOnPath(IntPtr, Int32, SKPath, SKPoint, SKPaint) |
Obsolete.
Draws text on the canvas following a path. |
| DrawTextOnPath(String, SKPath, Single, Single, SKPaint) |
Draws text on the canvas following a path. |
| DrawTextOnPath(String, SKPath, SKPoint, Boolean, SKFont, SKPaint) | |
| DrawTextOnPath(String, SKPath, SKPoint, Boolean, SKPaint) | |
| DrawTextOnPath(String, SKPath, SKPoint, SKPaint) |
Draws text on the canvas following a path. |
| DrawUrlAnnotation(SKRect, SKData) |
Annotates the canvas by associating the specified URL with the specified rectangle (in local coordinates). |
| DrawUrlAnnotation(SKRect, String) |
Annotates the canvas by associating the specified URL with the specified rectangle (in local coordinates). |
| DrawVertices(SKVertexMode, SKPoint[], SKColor[], SKPaint) |
Draws an array of vertices, interpreted as triangles (based on mode). |
| DrawVertices(SKVertexMode, SKPoint[], SKPoint[], SKColor[], SKBlendMode, UInt16[], SKPaint) |
Draws an array of vertices, interpreted as triangles (based on mode). |
| DrawVertices(SKVertexMode, SKPoint[], SKPoint[], SKColor[], SKPaint) |
Draws an array of vertices, interpreted as triangles (based on mode). |
| DrawVertices(SKVertexMode, SKPoint[], SKPoint[], SKColor[], UInt16[], SKPaint) |
Draws an array of vertices, interpreted as triangles (based on mode). |
| DrawVertices(SKVertices, SKBlendMode, SKPaint) |
Draws a set of vertices. |
| Flush() |
Triggers the immediate execution of all pending draw operations. |
| GetDeviceClipBounds(SKRectI) |
Returns the bounds of the current clip (in device coordinates). |
| GetLocalClipBounds(SKRect) |
Returns the bounds of the current clip (in local coordinates). |
| QuickReject(SKPath) |
Checks to see if the specified path, after being transformed by the current matrix, would lie completely outside of the current clip. |
| QuickReject(SKRect) |
Checks to see if the specified rectangle, after being transformed by the current matrix, would lie completely outside of the current clip. |
| ResetMatrix() |
Sets the current matrix to identity. |
| Restore() |
Restore the canvas state. |
| RestoreToCount(Int32) |
Efficiently restores the state to a specific level. |
| RotateDegrees(Single, Single, Single) |
Pre-concatenates the current matrix with the specified rotation, around the specified point. |
| RotateDegrees(Single) |
Pre-concatenates the current matrix with the specified rotation. |
| RotateRadians(Single, Single, Single) |
Pre-concatenates the current matrix with the specified rotation, around the specified point. |
| RotateRadians(Single) |
Pre-concatenates the current matrix with the specified rotation. |
| Save() |
Saves the canvas state. |
| SaveLayer() | |
| SaveLayer(SKPaint) |
Saves the canvas state and allocates an offscreen bitmap. |
| SaveLayer(SKRect, SKPaint) |
Saves the canvas state and allocates an offscreen bitmap. |
| Scale(Single, Single, Single, Single) |
Pre-concatenates the current matrix with the specified scale, at the specific offset. |
| Scale(Single, Single) |
Pre-concatenates the current matrix with the specified scale. |
| Scale(Single) |
Pre-concatenates the current matrix with the specified scale. |
| Scale(SKPoint) |
Pre-concatenates the current matrix with the specified scale. |
| SetMatrix(SKMatrix) |
Replaces the current matrix with a copy of the specified matrix. |
| Skew(Single, Single) |
Pre-concatenates the current matrix with the specified skew. |
| Skew(SKPoint) |
Pre-concatenates the current matrix with the specified skew. |
| Translate(Single, Single) |
Pre-concatenates the current matrix with the specified translation. |
| Translate(SKPoint) |
Pre-concatenates the current matrix with the specified translation. |
