Meziantou.Framework

DrawingCanvas Struct

Namespace
Meziantou.Framework.Imaging.Drawing
Assembly
Meziantou.Framework.Imaging.dll
Package
Meziantou.Framework.Imaging 1.2.11
Source
DrawingCanvas.cs
Available in package assets
net10.0net11.0
  • Obsolete: Types with embedded references are not supported in this version of your compiler.

The drawing surface handed to the callback of ImageFrame.Draw or Image.Draw. It is only valid until the callback returns.

[Obsolete("Types with embedded references are not supported in this version of your compiler.", true)]
public readonly ref struct DrawingCanvas

Remarks

Coordinates. The origin is the top-left corner of the stored pixels and Y grows downward. Integer coordinates are pixel boundaries: the pixel (x, y) covers the square from (x, y) to (x + 1, y + 1). A rectangle on integer coordinates is therefore filled exactly, and a one-pixel horizontal line is crisp when its path runs through the middle of a row of pixels (y + 0.5). Shapes are clipped to the canvas; what lies outside is ignored, and so is what lies outside the clips of DrawingCanvas.Clip. Every coordinate must be a finite number whose magnitude does not exceed 16777216. A transformation of the canvas may send a drawing beyond that range: what goes beyond it is cut by it (the canvas with a margin of millions of pixels), as browsers draw what is visible, and only a coordinate that is no longer a finite number once transformed is rejected.

Antialiasing. Each pixel is painted in proportion to the area of it that the shape covers. That area is exact, including where the contours of a shape overlap or intersect themselves, and is rounded to the nearest 1/65536. A pixel that is not covered is left untouched, bit for bit; a pixel that is entirely covered by an opaque color receives exactly that color. Curves are replaced by chords that stay within 1/16 of a pixel of the curve. DrawingCanvas.Antialiasing draws with hard edges instead: a pixel is painted entirely or not at all.

Compositing. The paint is composited over the existing pixels (source-over) on the stored sample values, with straight alpha and exact integer arithmetic, rounded to nearest with ties upward. Pixel formats without alpha stay opaque. See Brush for the conversion of colors to the pixel format of the frame, and Brush.CompositeMode for the other ways a paint is combined with the pixels (replacing, erasing, painting behind, masking), and Brush.BlendMode for the ways its color is mixed with theirs (multiplying, screening, tinting). DrawingCanvas.Compositing combines the paints with the pixels in linear light instead of on the stored sample values.

Floating-point canvases. On an RgbaFloat or RgbaHalf canvas, the paints have 16-bit colors and are composited over the stored values without clipping them, and color matrices are applied in place: additive composites and color matrices can leave samples outside [0, 1]. Layers, filters, blurs, shadows and masks draw on images of 16-bit samples, but what reads the pixels of the canvas back as 16-bit colors (DrawingCanvas.BackdropLayer, DrawingCanvas.BlurBackdrop, a DrawingCanvas.Group that is not isolated, a DrawingCanvas.KnockoutElement outside a knockout group) rejects such a sample with an UnsupportedImageFeatureException instead of clipping it. Drawing a floating-point image (DrawingCanvas.DrawImage, ImageBrush) on a floating-point canvas preserves its sample range and precision; drawing it on an integer canvas still rejects out-of-range samples. To use those effects on highlights, draw on an Rgba64 copy (Image.CloneAs with options that clip or tone map the samples).

Failures. Drawing is a pixel-only edit: when a call fails or is canceled, the calls that completed stay, and some rows of the failing call may be painted. A call rents all its working storage before it changes a pixel, so a call that exceeds ImageResourceLimits.MaxLiveAllocationBytes changes nothing.

Properties

NameDescription
HeightGets the height of the canvas, in pixels (0 for a default instance).
WidthGets the width of the canvas, in pixels (0 for a default instance).

Height

DrawingCanvas.cs

Gets the height of the canvas, in pixels (0 for a default instance).

public int Height { get; }

Property value

int

Width

DrawingCanvas.cs

Gets the width of the canvas, in pixels (0 for a default instance).

public int Width { get; }

Property value

int

Methods

NameDescription
Antialiasing(bool, DrawingAction)Runs a callback whose drawings have hard edges, or antialiased ones: pixel art, a mask of whole pixels, an image whose colors must stay those of a palette.
Antialiasing<TState>(bool, TState, DrawingAction<TState>)Runs a callback whose drawings have hard edges, or antialiased ones, passing caller state to avoid closure allocations.
BackdropLayer(Filter?, RectangleD, double, DrawingAction, CompositeMode, BlendMode)Runs a callback whose drawings are made on a layer that starts with what is already drawn behind a rectangle, filtered: the backdrop-filter property of CSS (frosted glass, a dimmed or grayed backdrop, the shadow of what is behind).
BackdropLayer(Filter?, RectangleD, double, DrawingAction, CompositeMode, BlendMode, LayerOpacity)Runs a callback whose drawings are made on a layer that starts with the filtered backdrop of a rectangle, with an opacity that is a coverage or the group opacity of CSS.
BackdropLayer<TState>(Filter?, RectangleD, double, TState, DrawingAction<TState>, CompositeMode, BlendMode)Runs a callback whose drawings are made on a layer that starts with the filtered backdrop of a rectangle, passing caller state to avoid closure allocations.
BackdropLayer<TState>(Filter?, RectangleD, double, TState, DrawingAction<TState>, CompositeMode, BlendMode, LayerOpacity)Runs a callback whose drawings are made on a layer that starts with the filtered backdrop of a rectangle, with an opacity that is a coverage or the group opacity of CSS, passing caller state to avoid closure allocations.
Blur(double, DrawingAction)Runs a callback whose drawings are blurred, as a whole, before they are drawn on the canvas: a soft light, something out of focus.
Blur<TState>(double, TState, DrawingAction<TState>)Runs a callback whose drawings are blurred before they are drawn on the canvas, passing caller state to avoid closure allocations.
BlurBackdrop(double)Blurs what is already drawn, where the clip lets a drawing through: the frosted glass behind a panel.
Clear(Rgba64)Replaces every pixel of the canvas by a color, alpha included: a transparent color erases the canvas.
Clip(VectorPath, DrawingAction, FillRule)Runs a callback whose drawings only change the inside of a path.
Clip(RectangleD, DrawingAction)Runs a callback whose drawings only change the inside of a rectangle.
Clip<TState>(VectorPath, TState, DrawingAction<TState>, FillRule)Runs a callback whose drawings only change the inside of a path, passing caller state to avoid closure allocations.
Clip<TState>(RectangleD, TState, DrawingAction<TState>)Runs a callback whose drawings only change the inside of a rectangle, passing caller state to avoid closure allocations.
Compositing(CompositingSpace, DrawingAction)Runs a callback whose paints are combined with the pixels in a numeric space: the stored sample values, or linear light.
Compositing<TState>(CompositingSpace, TState, DrawingAction<TState>)Runs a callback whose paints are combined with the pixels in a numeric space, passing caller state to avoid closure allocations.
DrawImage(ImageFrame, AffineTransform, ImageSampling, double)Draws the pixels of a frame of another image, placed on the canvas by a transformation, read in a given way.
DrawImage(ImageFrame, AffineTransform, double)Draws the pixels of a frame of another image, placed on the canvas by a transformation: turned, scaled, skewed or mirrored.
DrawImage(ImageFrame, PointD, PointD, PointD, PointD, ImageSampling, double)Draws a frame of another image on a quadrilateral, as it is seen in perspective: on a screen, a page or a wall of a photograph.
DrawImage(ImageFrame, PointD, double)Draws the pixels of a frame of another image, without scaling them.
DrawImage(ImageFrame, ProjectiveTransform, ImageSampling, double)Draws the pixels of a frame of another image, placed on the canvas by a projective transformation: the image seen in perspective.
DrawImage(ImageFrame, Rectangle, RectangleD, ImageSampling, double)Draws a region of the pixels of a frame of another image, stretched to a rectangle, read in a given way.
DrawImage(ImageFrame, Rectangle, RectangleD, double)Draws some of the pixels of a frame of another image, stretched to a rectangle.
DrawImage(ImageFrame, RectangleD, ImageSampling, double)Draws the pixels of a frame of another image, stretched to a rectangle, read in a given way.
DrawImage(ImageFrame, RectangleD, RectangleD, ImageSampling, double)Draws a rectangle of a frame of another image that need not be made of whole pixels, stretched to a rectangle: drawImage of the HTML canvas with a source rectangle.
DrawImage(ImageFrame, RectangleD, double)Draws the pixels of a frame of another image, stretched to a rectangle.
Fill(Brush)Paints the whole canvas.
Fill(Brush, VectorPath, FillRule)Paints the inside of a path. Open contours are closed by a straight segment.
FillCircle(Brush, PointD, double)Paints a disk.
FillClosedCurve(Brush, ReadOnlySpan<PointD>, double, FillRule)Paints the inside of the closed curve that goes smoothly through consecutive points, and from the last one back to the first one.
FillEllipse(Brush, PointD, double, double)Paints an ellipse whose axes are horizontal and vertical.
FillGlyphs(Brush, Font, double, ReadOnlySpan<PositionedGlyph>, GlyphRunOptions?)Fills a run of glyphs placed by the caller: the glyphs of a font at the positions a text shaper gives.
FillPie(Brush, PointD, double, double, double)Paints a slice of a disk: the part between two radii and the arc that joins them.
FillPolygon(Brush, ReadOnlySpan<PointD>, FillRule)Paints the inside of the closed contour made of straight segments between consecutive points.
FillRectangle(Brush, RectangleD)Paints a rectangle.
FillRoundedRectangle(Brush, RectangleD, CornerRadii)Paints a rectangle whose corners are quarters of circles, each with its own radius.
FillRoundedRectangle(Brush, RectangleD, double)Paints a rectangle whose corners are quarters of a circle.
FillText(Brush, TextLayout, VectorPath, TextPathOptions?)Paints the glyphs of a text layout along a path.
FillText(Brush, TextLayout, PointD)Paints the glyphs of a text layout.
FillText(Brush, string, Font, double, PointD)Lays out a text on one line per line of the text and paints its glyphs.
Filter(ColorMatrix, DrawingAction)Runs a callback whose drawings get new colors, as a whole, before they are drawn on the canvas: a photograph in gray levels, an icon in another color, a drawing that is dimmed.
Filter(Filter, DrawingAction)Runs a callback whose drawings go through a filter, as a whole, before they are drawn on the canvas: the filter property of CSS.
Filter<TState>(ColorMatrix, TState, DrawingAction<TState>)Runs a callback whose drawings get new colors before they are drawn on the canvas, passing caller state to avoid closure allocations.
Filter<TState>(Filter, TState, DrawingAction<TState>)Runs a callback whose drawings go through a filter before they are drawn, passing caller state to avoid closure allocations.
FilterBackdrop(ColorMatrix)Gives new colors to what is already drawn, where the clip lets a drawing through: the background of a dialog that is dimmed, a region that is shown in gray levels or inverted.
Flattening(double, DrawingAction)Runs a callback whose curves are replaced by chords closer to them than the 1/16 of a pixel a canvas starts with.
Flattening<TState>(double, TState, DrawingAction<TState>)Runs a callback whose curves are replaced by chords closer to them, passing caller state to avoid closure allocations.
Group(GroupOptions, DrawingAction, DrawingAction?)Runs a callback whose drawings are made in a group, which is composited as a whole when it ends.
Group<TState>(GroupOptions, TState, DrawingAction<TState>, DrawingAction<TState>?)Runs a callback whose drawings are made in a group, which is composited as a whole when it ends, passing caller state to avoid closure allocations.
HighPrecision(DrawingAction)Runs a callback whose drawings are made with 16-bit samples, and rounded to the samples of the canvas once when it returns.
HighPrecision<TState>(TState, DrawingAction<TState>)Runs a callback whose drawings are made with 16-bit samples, passing caller state to avoid closure allocations.
InnerShadow(Rgba64, PointD, double, DrawingAction)Runs a callback whose drawings are drawn with a shadow inside them: the shadow cast on them by what is around them, for a shape that looks cut out or pressed in.
InnerShadow<TState>(Rgba64, PointD, double, TState, DrawingAction<TState>)Runs a callback whose drawings are drawn with a shadow inside them, passing caller state to avoid closure allocations.
KnockoutElement(double, DrawingAction, DrawingAction?, MaskMode)Runs a callback that draws an element of the knockout group whose canvas this is.
KnockoutElement<TState>(double, TState, DrawingAction<TState>, DrawingAction<TState>?, MaskMode)Runs a callback that draws an element of the knockout group whose canvas this is, passing caller state to avoid closure allocations.
Layer(RectangleD, double, DrawingAction, CompositeMode, BlendMode)Runs a callback whose drawings are made on a transparent layer that holds the pixels of a rectangle only, which is then drawn on the canvas as a whole.
Layer(RectangleD, double, DrawingAction, CompositeMode, BlendMode, LayerOpacity)Runs a callback whose drawings are made on a transparent layer that holds the pixels of a rectangle only, with an opacity that is a coverage or the group opacity of CSS.
Layer(double, DrawingAction, CompositeMode, BlendMode)Runs a callback whose drawings are made on a transparent layer, which is then drawn on the canvas as a whole: with an opacity, or with an operator.
Layer(double, DrawingAction, CompositeMode, BlendMode, LayerOpacity)Runs a callback whose drawings are made on a transparent layer, which is then drawn on the canvas as a whole, with an opacity that is a coverage or the group opacity of CSS.
Layer<TState>(RectangleD, double, TState, DrawingAction<TState>, CompositeMode, BlendMode)Runs a callback whose drawings are made on a transparent layer that holds the pixels of a rectangle only, passing caller state to avoid closure allocations.
Layer<TState>(RectangleD, double, TState, DrawingAction<TState>, CompositeMode, BlendMode, LayerOpacity)Runs a callback whose drawings are made on a transparent layer that holds the pixels of a rectangle only, with an opacity that is a coverage or the group opacity of CSS, passing caller state to avoid closure allocations.
Layer<TState>(double, TState, DrawingAction<TState>, CompositeMode, BlendMode)Runs a callback whose drawings are made on a transparent layer, which is then drawn on the canvas as a whole, passing caller state to avoid closure allocations.
Layer<TState>(double, TState, DrawingAction<TState>, CompositeMode, BlendMode, LayerOpacity)Runs a callback whose drawings are made on a transparent layer, with an opacity that is a coverage or the group opacity of CSS, passing caller state to avoid closure allocations.
Mask(DrawingAction, DrawingAction, MaskMode)Runs a callback whose drawings are kept only where a mask is: the drawings of another callback, by their opacity or by their luminance.
Mask<TState>(TState, DrawingAction<TState>, DrawingAction<TState>, MaskMode)Runs a callback whose drawings are kept only where a mask is, passing caller state to both callbacks to avoid closure allocations.
PaintProfile(IccProfile, DrawingAction, IccColorTransformOptions?)Runs a callback whose paint colors are colors of an ICC profile: they are converted to the color space of the image before they are painted.
PaintProfile<TState>(IccProfile, TState, DrawingAction<TState>, IccColorTransformOptions?)Runs a callback whose paint colors are colors of an ICC profile, passing caller state to avoid closure allocations.
Shadow(Rgba64, PointD, double, DrawingAction)Runs a callback whose drawings are drawn with their shadow: a drop shadow, or a glow without offset.
Shadow<TState>(Rgba64, PointD, double, TState, DrawingAction<TState>)Runs a callback whose drawings are drawn with their shadow, passing caller state to avoid closure allocations.
Stroke(Pen, VectorPath)Paints the outline of a path.
StrokeArc(Pen, PointD, double, double, double)Paints an arc of a circle, with the caps of the pen at both ends.
StrokeBezier(Pen, PointD, PointD, PointD)Paints a quadratic Bézier curve, with the caps of the pen at both ends.
StrokeBezier(Pen, PointD, PointD, PointD, PointD)Paints a cubic Bézier curve, with the caps of the pen at both ends.
StrokeCircle(Pen, PointD, double)Paints the outline of a circle.
StrokeClosedCurve(Pen, ReadOnlySpan<PointD>, double)Paints the outline of the closed curve that goes smoothly through consecutive points, and from the last one back to the first one.
StrokeCurve(Pen, ReadOnlySpan<PointD>, double)Paints a curve that goes smoothly through consecutive points, with the caps of the pen at both ends: the line of a chart.
StrokeEllipse(Pen, PointD, double, double)Paints the outline of an ellipse whose axes are horizontal and vertical.
StrokeGlyphs(Pen, Font, double, ReadOnlySpan<PositionedGlyph>, GlyphRunOptions?)Strokes the outlines of a run of glyphs placed by the caller, as one shape: strokeText of the HTML canvas.
StrokeLine(Pen, PointD, PointD)Paints a straight line, with the caps of the pen at both ends.
StrokePolygon(Pen, ReadOnlySpan<PointD>)Paints the outline of the closed contour made of straight segments between consecutive points.
StrokePolyline(Pen, ReadOnlySpan<PointD>)Paints the straight segments between consecutive points, with the caps of the pen at both ends.
StrokeRectangle(Pen, RectangleD)Paints the outline of a rectangle. The stroke is centered on the sides of the rectangle.
StrokeRoundedRectangle(Pen, RectangleD, CornerRadii)Paints the outline of a rectangle whose corners are quarters of circles, each with its own radius. The stroke is centered on the outline.
StrokeRoundedRectangle(Pen, RectangleD, double)Paints the outline of a rectangle whose corners are quarters of a circle. The stroke is centered on the outline.
StrokeText(Pen, TextLayout, VectorPath, TextPathOptions?)Paints the outlines of the glyphs of a text layout along a path, with a pen.
StrokeText(Pen, TextLayout, PointD)Paints the outlines of the glyphs of a text layout with a pen.
Transform(AffineTransform, DrawingAction)Runs a callback whose drawings are transformed: moved, turned, scaled, skewed or mirrored.
Transform(ProjectiveTransform, DrawingAction)Runs a callback whose drawings are transformed by a projective transformation: drawn on a plane seen in perspective.
Transform(Transform3D, DrawingAction)Runs a callback whose drawings are the plane z = 0 transformed by a transformation of space: turned in three dimensions and seen in perspective, as by the 3D transforms of CSS.
Transform<TState>(AffineTransform, TState, DrawingAction<TState>)Runs a callback whose drawings are transformed, passing caller state to avoid closure allocations.
Transform<TState>(ProjectiveTransform, TState, DrawingAction<TState>)Runs a callback whose drawings are transformed by a projective transformation, passing caller state to avoid closure allocations.
Transform<TState>(Transform3D, TState, DrawingAction<TState>)Runs a callback whose drawings are transformed by a transformation of space, passing caller state to avoid closure allocations.

Antialiasing overloads

Antialiasing(bool, DrawingAction)

DrawingCanvas.cs

Runs a callback whose drawings have hard edges, or antialiased ones: pixel art, a mask of whole pixels, an image whose colors must stay those of a palette.

public void Antialiasing(bool enabled, DrawingAction action)
Parameters
enabled bool
false for hard edges; true (what a canvas starts with) for antialiased ones, inside a callback that turned them off.
action DrawingAction
The callback that draws. It must not be asynchronous and must not retain the canvas.
Exceptions
ArgumentNullException
action is null.
InvalidOperationException
The callback that received the canvas has returned.
OperationCanceledException
The operation was canceled.
Remarks

Without antialiasing, a pixel is painted entirely or not at all, as browsers draw hard edges: it is painted when its center is inside the shape, a center on the top or the left side of the shape being outside and one on its bottom or its right side inside. An opaque paint then writes its color and nothing else: no pixel gets a color between the paint and what was under it. This applies to the shapes, the strokes, the texts and the edges of the images that are drawn while the callback runs, and to the clips that start in it.

What is not an edge is unchanged: the opacity of a paint, of an image or of a layer, the blur of a shadow, the pixels inside an image, and the glyphs a font draws with its own colors. A thin line is drawn where it covers the centers of pixels: a horizontal line one pixel wide between two rows of centers covers one of them.

Antialiasing<TState>(bool, TState, DrawingAction<TState>)

DrawingCanvas.cs

Runs a callback whose drawings have hard edges, or antialiased ones, passing caller state to avoid closure allocations.

public void Antialiasing<TState>(bool enabled, TState state, DrawingAction<TState> action) where TState : allows ref struct
Type parameters
TState
The type of the state.
Parameters
enabled bool
false for hard edges; true for antialiased ones.
state TState
The state passed to action.
action DrawingAction<TState>
The callback that draws. Use a static lambda to avoid allocations. It must not retain the canvas.
Exceptions
ArgumentNullException
action is null.
InvalidOperationException
The callback that received the canvas has returned.
OperationCanceledException
The operation was canceled.
Remarks

See DrawingCanvas.Antialiasing.

BackdropLayer overloads

BackdropLayer(Filter?, RectangleD, double, DrawingAction, CompositeMode, BlendMode)

DrawingCanvas.cs

Runs a callback whose drawings are made on a layer that starts with what is already drawn behind a rectangle, filtered: the backdrop-filter property of CSS (frosted glass, a dimmed or grayed backdrop, the shadow of what is behind).

public void BackdropLayer(Filter? filter, RectangleD bounds, double opacity, DrawingAction action, CompositeMode compositeMode = CompositeMode.SourceOver, BlendMode blendMode = BlendMode.Normal)
Parameters
filter Filter?
The filter of the backdrop, or null to start with the backdrop as it is.
bounds RectangleD
The rectangle of the backdrop, in the coordinates of the drawing.
opacity double
The opacity of the layer, from 0 to 1.
action DrawingAction
The callback that draws on the backdrop. It must not be asynchronous and must not retain the canvas.
compositeMode CompositeMode
The operator that combines the layer with the canvas.
blendMode BlendMode
The blend mode that mixes the colors of the layer with those of the canvas.
Exceptions
ArgumentNullException
action is null.
ArgumentException
A coordinate of bounds is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate of bounds exceeds 16777216, opacity is not between 0 and 1, compositeMode is not a defined CompositeMode, or blendMode is not a defined BlendMode.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The layer or the working storage would exceed the allocation limit.
OperationCanceledException
The operation was canceled.
UnsupportedImageFeatureException
A floating-point sample of the canvas that it reads is outside [0, 1] or is not a number, and has no 16-bit color (see the remarks of DrawingCanvas).
Remarks

The backdrop is the pixels already drawn (on the canvas, or on the layer this one starts in) whose center is in the rectangle on the canvas (in the box of its image under a transformation of the canvas). It goes through the filter as an image of its own, whose pixels are mirrored beyond its edges, whatever the edge modes of the filter: a blur of a backdrop does not fade at its edges. The result is the start of a layer (see DrawingCanvas.Layer), transparent around it; the callback draws on it, then the layer is drawn on the canvas with the opacity, the operator and the blend mode. A clip that is active when the layer starts (the rounded corners of a panel) applies to the layer as a whole.

The lengths of the filter are lengths of the drawing, which the linear part of the transformation of the canvas scales: a deviation along an axis by the length of the image of the unit vector of that axis. When an image of several frames is drawn on, each frame starts with its own backdrop.

BackdropLayer(Filter?, RectangleD, double, DrawingAction, CompositeMode, BlendMode, LayerOpacity)

DrawingCanvas.cs

Runs a callback whose drawings are made on a layer that starts with the filtered backdrop of a rectangle, with an opacity that is a coverage or the group opacity of CSS.

public void BackdropLayer(Filter? filter, RectangleD bounds, double opacity, DrawingAction action, CompositeMode compositeMode, BlendMode blendMode, LayerOpacity opacityMode)
Parameters
filter Filter?
The filter of the backdrop, or null to start with the backdrop as it is.
bounds RectangleD
The rectangle of the backdrop, in the coordinates of the drawing.
opacity double
The opacity of the layer, from 0 to 1.
action DrawingAction
The callback that draws on the backdrop. It must not be asynchronous and must not retain the canvas.
compositeMode CompositeMode
The operator that combines the layer with the canvas.
blendMode BlendMode
The blend mode that mixes the colors of the layer with those of the canvas.
opacityMode LayerOpacity
How the opacity combines with the operator.
Exceptions
ArgumentNullException
action is null.
ArgumentException
A coordinate of bounds is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate of bounds exceeds 16777216, opacity is not between 0 and 1, compositeMode is not a defined CompositeMode, blendMode is not a defined BlendMode, or opacityMode is not a defined LayerOpacity.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The layer or the working storage would exceed the allocation limit.
OperationCanceledException
The operation was canceled.
UnsupportedImageFeatureException
A floating-point sample of the canvas that it reads is outside [0, 1] or is not a number, and has no 16-bit color (see the remarks of DrawingCanvas).
Remarks

See DrawingCanvas.BackdropLayer and, for opacityMode, DrawingCanvas.Layer.

BackdropLayer<TState>(Filter?, RectangleD, double, TState, DrawingAction<TState>, CompositeMode, BlendMode)

DrawingCanvas.cs

Runs a callback whose drawings are made on a layer that starts with the filtered backdrop of a rectangle, passing caller state to avoid closure allocations.

public void BackdropLayer<TState>(Filter? filter, RectangleD bounds, double opacity, TState state, DrawingAction<TState> action, CompositeMode compositeMode = CompositeMode.SourceOver, BlendMode blendMode = BlendMode.Normal) where TState : allows ref struct
Type parameters
TState
The type of the state.
Parameters
filter Filter?
The filter of the backdrop, or null to start with the backdrop as it is.
bounds RectangleD
The rectangle of the backdrop, in the coordinates of the drawing.
opacity double
The opacity of the layer, from 0 to 1.
state TState
The state passed to action.
action DrawingAction<TState>
The callback that draws on the backdrop. Use a static lambda to avoid allocations. It must not retain the canvas.
compositeMode CompositeMode
The operator that combines the layer with the canvas.
blendMode BlendMode
The blend mode that mixes the colors of the layer with those of the canvas.
Exceptions
ArgumentNullException
action is null.
ArgumentException
A coordinate of bounds is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate of bounds exceeds 16777216, opacity is not between 0 and 1, compositeMode is not a defined CompositeMode, or blendMode is not a defined BlendMode.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The layer or the working storage would exceed the allocation limit.
OperationCanceledException
The operation was canceled.
UnsupportedImageFeatureException
A floating-point sample of the canvas that it reads is outside [0, 1] or is not a number, and has no 16-bit color (see the remarks of DrawingCanvas).
Remarks

See DrawingCanvas.BackdropLayer.

BackdropLayer<TState>(Filter?, RectangleD, double, TState, DrawingAction<TState>, CompositeMode, BlendMode, LayerOpacity)

DrawingCanvas.cs

Runs a callback whose drawings are made on a layer that starts with the filtered backdrop of a rectangle, with an opacity that is a coverage or the group opacity of CSS, passing caller state to avoid closure allocations.

public void BackdropLayer<TState>(Filter? filter, RectangleD bounds, double opacity, TState state, DrawingAction<TState> action, CompositeMode compositeMode, BlendMode blendMode, LayerOpacity opacityMode) where TState : allows ref struct
Type parameters
TState
The type of the state.
Parameters
filter Filter?
The filter of the backdrop, or null to start with the backdrop as it is.
bounds RectangleD
The rectangle of the backdrop, in the coordinates of the drawing.
opacity double
The opacity of the layer, from 0 to 1.
state TState
The state passed to action.
action DrawingAction<TState>
The callback that draws on the backdrop. Use a static lambda to avoid allocations. It must not retain the canvas.
compositeMode CompositeMode
The operator that combines the layer with the canvas.
blendMode BlendMode
The blend mode that mixes the colors of the layer with those of the canvas.
opacityMode LayerOpacity
How the opacity combines with the operator.
Exceptions
ArgumentNullException
action is null.
ArgumentException
A coordinate of bounds is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate of bounds exceeds 16777216, opacity is not between 0 and 1, compositeMode is not a defined CompositeMode, blendMode is not a defined BlendMode, or opacityMode is not a defined LayerOpacity.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The layer or the working storage would exceed the allocation limit.
OperationCanceledException
The operation was canceled.
UnsupportedImageFeatureException
A floating-point sample of the canvas that it reads is outside [0, 1] or is not a number, and has no 16-bit color (see the remarks of DrawingCanvas).
Remarks

See DrawingCanvas.BackdropLayer.

Blur overloads

Blur(double, DrawingAction)

DrawingCanvas.cs

Runs a callback whose drawings are blurred, as a whole, before they are drawn on the canvas: a soft light, something out of focus.

public void Blur(double blur, DrawingAction action)
Parameters
blur double
The standard deviation of the blur, in pixels: 0 for no blur. Must be between 0 and 10000.
action DrawingAction
The callback that draws. It must not be asynchronous and must not retain the canvas.
Exceptions
ArgumentNullException
action is null.
ArgumentException
blur is not a finite number.
ArgumentOutOfRangeException
blur is negative or exceeds 10000.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The layer or the working storage would exceed the allocation limit.
OperationCanceledException
The operation was canceled.
Remarks

The drawings are made on a layer (see DrawingCanvas.Layer). When the callback returns, the layer is blurred by a Gaussian blur of standard deviation blur, colors and alpha together (the colors are weighted by their alpha, so a transparent pixel does not darken its neighbors), then drawn on the canvas.

A drawing that goes beyond an edge of the canvas is taken to continue as it does on that edge. A clip that is active when the callback starts applies to the result; what is drawn around it still spreads into it. The time and the storage grow with the pixels the clip can show and with the blur. Under a transformation of the canvas, the blur is enlarged with the drawing.

Blur<TState>(double, TState, DrawingAction<TState>)

DrawingCanvas.cs

Runs a callback whose drawings are blurred before they are drawn on the canvas, passing caller state to avoid closure allocations.

public void Blur<TState>(double blur, TState state, DrawingAction<TState> action) where TState : allows ref struct
Type parameters
TState
The type of the state.
Parameters
blur double
The standard deviation of the blur, in pixels. Must be between 0 and 10000.
state TState
The state passed to action.
action DrawingAction<TState>
The callback that draws. Use a static lambda to avoid allocations. It must not retain the canvas.
Exceptions
ArgumentNullException
action is null.
ArgumentException
blur is not a finite number.
ArgumentOutOfRangeException
blur is negative or exceeds 10000.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The layer or the working storage would exceed the allocation limit.
OperationCanceledException
The operation was canceled.
Remarks

See DrawingCanvas.Blur.

BlurBackdrop(double)

DrawingCanvas.cs

Blurs what is already drawn, where the clip lets a drawing through: the frosted glass behind a panel.

public void BlurBackdrop(double blur)

Parameters

blur double
The standard deviation of the blur, in pixels: 0 changes nothing. Must be between 0 and 10000.

Exceptions

ArgumentException
blur is not a finite number.
ArgumentOutOfRangeException
blur is negative or exceeds 10000.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.
UnsupportedImageFeatureException
A floating-point sample of the canvas that it reads is outside [0, 1] or is not a number, and has no 16-bit color (see the remarks of DrawingCanvas).

Remarks

The pixels of the canvas (of the layer, inside DrawingCanvas.Layer) are replaced by their Gaussian blur of standard deviation blur, colors and alpha together. Without a clip, the whole canvas is blurred; inside DrawingCanvas.Clip, only the inside of the clip is, and a pixel on its edge in proportion to the area of it that is inside. What is around the clip is read by the blur, but not changed.

The pixels are read as 16-bit colors and the result is converted to the pixel format like a brush color. What is beyond an edge of the canvas is taken to continue as on that edge. This is not a drawing: the blend mode and the operator of a brush do not apply, and neither does the opacity of a layer the canvas is not inside. The time grows with the pixels that are blurred and with the blur.

Clear(Rgba64)

DrawingCanvas.cs

Replaces every pixel of the canvas by a color, alpha included: a transparent color erases the canvas.

public void Clear(Rgba64 color)

Parameters

color Rgba64
The color, with straight alpha. An Rgba32 converts implicitly.

Exceptions

InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.

Remarks

This is filling the canvas with CompositeMode.Source; DrawingCanvas.Fill paints over the pixels instead. On a pixel format without alpha, the pixels get the color multiplied by its alpha.

Clip overloads

Clip(VectorPath, DrawingAction, FillRule)

DrawingCanvas.cs

Runs a callback whose drawings only change the inside of a path.

public void Clip(VectorPath path, DrawingAction action, FillRule fillRule = FillRule.NonZero)
Parameters
path VectorPath
The path. Open contours are closed by a straight segment.
action DrawingAction
The callback that draws. It must not be asynchronous and must not retain the canvas.
fillRule FillRule
The rule deciding what is inside when contours overlap.
Exceptions
ArgumentNullException
path or action is null.
ArgumentOutOfRangeException
fillRule is not a defined FillRule.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The working storage would exceed the allocation limit. The callback is not run.
OperationCanceledException
The operation was canceled.
Remarks

The clip lasts as long as the callback, and applies to every drawing made with the canvas it receives: DrawingCanvas.Fill then paints the inside of the path. A clip started inside another one keeps what both let through.

The edge of a clip is antialiased like the edge of a shape: each pixel has the area of it that is inside the path, and the coverage of what is drawn is multiplied by it, rounded to the nearest 1/65536. A pixel on the edge of both a shape and the clip therefore gets the product of the two areas, not the area of what they have in common. The clip keeps one value per pixel of the bounds of the path, rented from the allocation scope of the image when the clip starts.

Clip(RectangleD, DrawingAction)

DrawingCanvas.cs

Runs a callback whose drawings only change the inside of a rectangle.

public void Clip(RectangleD rectangle, DrawingAction action)
Parameters
rectangle RectangleD
The rectangle. A Rectangle of pixels converts implicitly.
action DrawingAction
The callback that draws. It must not be asynchronous and must not retain the canvas.
Exceptions
ArgumentNullException
action is null.
ArgumentException
A coordinate is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate exceeds 16777216.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The working storage would exceed the allocation limit. The callback is not run.
OperationCanceledException
The operation was canceled.
Remarks

A rectangle on whole coordinates (a Rectangle of pixels) is exact and costs nothing: its pixels are in or out. Any other rectangle is a clip like the one of a path: see DrawingCanvas.Clip.

Clip<TState>(VectorPath, TState, DrawingAction<TState>, FillRule)

DrawingCanvas.cs

Runs a callback whose drawings only change the inside of a path, passing caller state to avoid closure allocations.

public void Clip<TState>(VectorPath path, TState state, DrawingAction<TState> action, FillRule fillRule = FillRule.NonZero) where TState : allows ref struct
Type parameters
TState
The type of the state.
Parameters
path VectorPath
The path. Open contours are closed by a straight segment.
state TState
The state passed to action.
action DrawingAction<TState>
The callback that draws. Use a static lambda to avoid allocations. It must not retain the canvas.
fillRule FillRule
The rule deciding what is inside when contours overlap.
Exceptions
ArgumentNullException
path or action is null.
ArgumentOutOfRangeException
fillRule is not a defined FillRule.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The working storage would exceed the allocation limit. The callback is not run.
OperationCanceledException
The operation was canceled.
Remarks

See DrawingCanvas.Clip.

Clip<TState>(RectangleD, TState, DrawingAction<TState>)

DrawingCanvas.cs

Runs a callback whose drawings only change the inside of a rectangle, passing caller state to avoid closure allocations.

public void Clip<TState>(RectangleD rectangle, TState state, DrawingAction<TState> action) where TState : allows ref struct
Type parameters
TState
The type of the state.
Parameters
rectangle RectangleD
The rectangle. A Rectangle of pixels converts implicitly.
state TState
The state passed to action.
action DrawingAction<TState>
The callback that draws. Use a static lambda to avoid allocations. It must not retain the canvas.
Exceptions
ArgumentNullException
action is null.
ArgumentException
A coordinate is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate exceeds 16777216.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The working storage would exceed the allocation limit. The callback is not run.
OperationCanceledException
The operation was canceled.
Remarks

See DrawingCanvas.Clip.

Compositing overloads

Compositing(CompositingSpace, DrawingAction)

DrawingCanvas.cs

Runs a callback whose paints are combined with the pixels in a numeric space: the stored sample values, or linear light.

public void Compositing(CompositingSpace space, DrawingAction action)
Parameters
space CompositingSpace
The space the paints are combined with the pixels in.
action DrawingAction
The callback that draws. It must not be asynchronous and must not retain the canvas.
Exceptions
ArgumentNullException
action is null.
ArgumentOutOfRangeException
space is not a defined CompositingSpace.
UnsupportedImageFeatureException
CompositingSpace.LinearSrgb is requested for an image whose ICC profile has no tone curve for each channel, or whose transfer characteristics are reserved. The callback is not run.
ImageResourceLimitException
The tables of the tone curves of the ICC profile of the image would exceed the allocation limit. The callback is not run.
InvalidOperationException
The callback that received the canvas has returned.
OperationCanceledException
The operation was canceled.
Remarks

With CompositingSpace.LinearSrgb, the samples of a paint and of the pixels it is drawn on are converted to linear light with the transfer function of the image (sRGB, unless the image declares another one or has an ICC profile with tone curves of its own: see CompositingSpace.LinearSrgb), combined (coverage, opacity, blend mode and operator, with the formulas of the stored values), and the result is converted back. The edge between two colors, a translucent paint and the blur of a shadow then mix light as light mixes: red over green goes through a yellow instead of a dark olive, and white text on black keeps its weight. DrawingCanvas.Blur and DrawingCanvas.BlurBackdrop blur light too. The alpha is not a color and is combined as it is.

The colors of the brushes are still sample values in the color space of the image, unless DrawingCanvas.PaintProfile says otherwise; a gradient mixes its stops as its GradientBrush.ColorSpace says, and an image is interpolated on its stored values. Layers hold samples of the image too: a drawing made on a layer is combined in linear light on the layer, and the layer on the canvas. The arithmetic is in double precision, and uses the power function of the platform: a sample within about 1e-12 of a rounding boundary can differ by one from a platform to another. A pixel that a shape does not touch is still left untouched, and an opaque paint that covers a pixel entirely still writes its color exactly.

Compositing<TState>(CompositingSpace, TState, DrawingAction<TState>)

DrawingCanvas.cs

Runs a callback whose paints are combined with the pixels in a numeric space, passing caller state to avoid closure allocations.

public void Compositing<TState>(CompositingSpace space, TState state, DrawingAction<TState> action) where TState : allows ref struct
Type parameters
TState
The type of the state.
Parameters
space CompositingSpace
The space the paints are combined with the pixels in.
state TState
The state passed to action.
action DrawingAction<TState>
The callback that draws. Use a static lambda to avoid allocations. It must not retain the canvas.
Exceptions
ArgumentNullException
action is null.
ArgumentOutOfRangeException
space is not a defined CompositingSpace.
UnsupportedImageFeatureException
CompositingSpace.LinearSrgb is requested for an image whose ICC profile has no tone curve for each channel, or whose transfer characteristics are reserved. The callback is not run.
ImageResourceLimitException
The tables of the tone curves of the ICC profile of the image would exceed the allocation limit. The callback is not run.
InvalidOperationException
The callback that received the canvas has returned.
OperationCanceledException
The operation was canceled.
Remarks

See DrawingCanvas.Compositing.

DrawImage overloads

DrawImage(ImageFrame, AffineTransform, ImageSampling, double)

DrawingCanvas.cs

Draws the pixels of a frame of another image, placed on the canvas by a transformation, read in a given way.

public void DrawImage(ImageFrame source, AffineTransform transform, ImageSampling sampling, double opacity = 1d)
Parameters
source ImageFrame
The frame to draw.
transform AffineTransform
The transformation that places the frame on the canvas.
sampling ImageSampling
How the image is read between the centers of its pixels.
opacity double
The opacity of the image, from 0 to 1.
Exceptions
ArgumentNullException
source is null.
ArgumentOutOfRangeException
The magnitude of a coordinate of a corner of the image on the canvas exceeds 16777216, sampling is not a defined ImageSampling, or opacity is not between 0 and 1.
InvalidOperationException
The callback that received the canvas has returned, or source is a frame that is being drawn on or whose pixels are being accessed.
ObjectDisposedException
source no longer belongs to a live image.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.
UnsupportedImageFeatureException
source has a floating-point sample outside [0, 1] or that is not a number where it is read, which has no 16-bit color.
Remarks

See DrawingCanvas.DrawImage and DrawingCanvas.DrawImage.

DrawImage(ImageFrame, AffineTransform, double)

DrawingCanvas.cs

Draws the pixels of a frame of another image, placed on the canvas by a transformation: turned, scaled, skewed or mirrored.

public void DrawImage(ImageFrame source, AffineTransform transform, double opacity = 1d)
Parameters
source ImageFrame
The frame to draw.
transform AffineTransform
The transformation that places the frame on the canvas.
opacity double
The opacity of the image, from 0 to 1.
Exceptions
ArgumentNullException
source is null.
ArgumentOutOfRangeException
The magnitude of a coordinate of a corner of the image on the canvas exceeds 16777216, or opacity is not between 0 and 1.
InvalidOperationException
The callback that received the canvas has returned, or source is a frame that is being drawn on or whose pixels are being accessed.
ObjectDisposedException
source no longer belongs to a live image.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.
UnsupportedImageFeatureException
source has a floating-point sample outside [0, 1] or that is not a number where it is read, which has no 16-bit color.
Remarks

The transformation applies to the image as it would be drawn at the origin of the canvas, without scaling: the pixel (i, j) of the frame is the square from (i, j) to (i + 1, j + 1) before it applies. AffineTransform.CreateRotation around the center of the frame, then a translation, draws the image turned around its center.

The edges of the image are antialiased as the edges of a shape are, and its pixels are interpolated (see ImageBrush, which this method is a shortcut for, with the pixels of the edges extended). A transformation that flattens the image to a line draws nothing. See DrawingCanvas.DrawImage.

DrawImage(ImageFrame, PointD, PointD, PointD, PointD, ImageSampling, double)

DrawingCanvas.cs

Draws a frame of another image on a quadrilateral, as it is seen in perspective: on a screen, a page or a wall of a photograph.

public void DrawImage(ImageFrame source, PointD topLeft, PointD topRight, PointD bottomRight, PointD bottomLeft, ImageSampling sampling = ImageSampling.Bilinear, double opacity = 1d)
Parameters
source ImageFrame
The frame to draw.
topLeft PointD
Where the top-left corner of the image is drawn.
topRight PointD
Where the top-right corner of the image is drawn.
bottomRight PointD
Where the bottom-right corner of the image is drawn.
bottomLeft PointD
Where the bottom-left corner of the image is drawn.
sampling ImageSampling
How the image is read between the centers of its pixels.
opacity double
The opacity of the image, from 0 to 1.
Exceptions
ArgumentNullException
source is null.
ArgumentException
A coordinate is not a finite number, or the points are not the corners of a convex quadrilateral, in order.
ArgumentOutOfRangeException
The magnitude of a coordinate exceeds 16777216, sampling is not a defined ImageSampling, or opacity is not between 0 and 1.
InvalidOperationException
The callback that received the canvas has returned, or source is a frame that is being drawn on or whose pixels are being accessed.
ObjectDisposedException
source no longer belongs to a live image.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.
UnsupportedImageFeatureException
source has a floating-point sample outside [0, 1] or that is not a number where it is read, which has no 16-bit color.
Remarks

The four corners of the image are drawn on the four points, and the image between them as a plane seen in perspective: straight lines of the image stay straight, and what is further away is smaller. When the points are the corners of a parallelogram, the image is not seen in perspective, and this is DrawingCanvas.DrawImage, with the same pixels.

The points must be the corners of a convex quadrilateral, given in order around it (either way: the other way around mirrors the image). Points that are all on one line draw nothing. The edges of the quadrilateral are antialiased, and the pixels on the edges of the image are extended, as for the other ways of drawing an image. With ImageSampling.Smooth, each pixel of the canvas reads what it covers of the image, which changes from the near side to the far side: use it for an image that the perspective reduces.

The frame is read while it is drawn: it must not be one of the frames the canvas draws on.

DrawImage(ImageFrame, PointD, double)

DrawingCanvas.cs

Draws the pixels of a frame of another image, without scaling them.

public void DrawImage(ImageFrame source, PointD position, double opacity = 1d)
Parameters
source ImageFrame
The frame to draw.
position PointD
The position of its top-left corner on the canvas. A Point converts implicitly.
opacity double
The opacity of the image, from 0 to 1.
Exceptions
ArgumentNullException
source is null.
ArgumentException
A coordinate is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate exceeds 16777216, or opacity is not between 0 and 1.
InvalidOperationException
The callback that received the canvas has returned, or source is a frame that is being drawn on or whose pixels are being accessed.
ObjectDisposedException
source no longer belongs to a live image.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.
UnsupportedImageFeatureException
source has a floating-point sample outside [0, 1] or that is not a number where it is read, which has no 16-bit color.
Remarks

The image is composited over the canvas like a paint, with its own alpha. At a position on whole pixels, its pixels are those of the source, exactly; elsewhere they are interpolated (see ImageBrush, which this method is a shortcut for, with the pixels of the edges extended). The pixels are converted to the pixel format of the canvas; no color profile is applied.

The frame is read while it is drawn: it must not be one of the frames the canvas draws on.

DrawImage(ImageFrame, ProjectiveTransform, ImageSampling, double)

DrawingCanvas.cs

Draws the pixels of a frame of another image, placed on the canvas by a projective transformation: the image seen in perspective.

public void DrawImage(ImageFrame source, ProjectiveTransform transform, ImageSampling sampling, double opacity = 1d)
Parameters
source ImageFrame
The frame to draw.
transform ProjectiveTransform
The transformation that places the pixels of the frame on the canvas.
sampling ImageSampling
How the image is read between the centers of its pixels.
opacity double
The opacity of the image, from 0 to 1.
Exceptions
ArgumentNullException
source is null.
ArgumentOutOfRangeException
sampling is not a defined ImageSampling, opacity is not between 0 and 1, or the transformation is affine and moves a corner of the image beyond 16777216.
InvalidOperationException
The callback that received the canvas has returned, or source is a frame that is being drawn on or whose pixels are being accessed.
ObjectDisposedException
source no longer belongs to a live image.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.
UnsupportedImageFeatureException
source has a floating-point sample outside [0, 1] or that is not a number where it is read, which has no 16-bit color.
Remarks

The pixel (x, y) of the frame covers the square from (x, y) to (x + 1, y + 1), which the transformation places on the canvas (then the transformation of the canvas). What is on the other side of the horizon of the transformation (where its W is not positive) is not drawn. The edges of the image are antialiased, and its pixels on the edges are extended, as for the other ways of drawing an image. An affine transformation draws what DrawingCanvas.DrawImage draws, with the same pixels.

With ImageSampling.Smooth, each pixel of the canvas reads what it covers of the image, which changes from the near side to the far side: use it for an image that the perspective reduces.

DrawImage(ImageFrame, Rectangle, RectangleD, ImageSampling, double)

DrawingCanvas.cs

Draws a region of the pixels of a frame of another image, stretched to a rectangle, read in a given way.

public void DrawImage(ImageFrame source, Rectangle sourceRegion, RectangleD destination, ImageSampling sampling, double opacity = 1d)
Parameters
source ImageFrame
The frame to draw.
sourceRegion Rectangle
The pixels of the frame that are drawn. Its pixels on the edges are extended; the pixels around it are not read.
destination RectangleD
The rectangle of the canvas the region fills. A Rectangle of pixels converts implicitly.
sampling ImageSampling
How the image is read between the centers of its pixels.
opacity double
The opacity of the image, from 0 to 1.
Exceptions
ArgumentNullException
source is null.
ArgumentException
A coordinate is not a finite number.
ArgumentOutOfRangeException
sourceRegion is not inside the frame, the magnitude of a coordinate exceeds 16777216, sampling is not a defined ImageSampling, or opacity is not between 0 and 1.
InvalidOperationException
The callback that received the canvas has returned, or source is a frame that is being drawn on or whose pixels are being accessed.
ObjectDisposedException
source no longer belongs to a live image.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.
UnsupportedImageFeatureException
source has a floating-point sample outside [0, 1] or that is not a number where it is read, which has no 16-bit color.
Remarks

See DrawingCanvas.DrawImage and DrawingCanvas.DrawImage.

DrawImage(ImageFrame, Rectangle, RectangleD, double)

DrawingCanvas.cs

Draws some of the pixels of a frame of another image, stretched to a rectangle.

public void DrawImage(ImageFrame source, Rectangle sourceRegion, RectangleD destination, double opacity = 1d)
Parameters
source ImageFrame
The frame to draw.
sourceRegion Rectangle
The pixels of the frame to draw. Must be inside the frame.
destination RectangleD
The rectangle of the canvas the region fills. A Rectangle of pixels converts implicitly.
opacity double
The opacity of the image, from 0 to 1.
Exceptions
ArgumentNullException
source is null.
ArgumentException
A coordinate is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate exceeds 16777216, sourceRegion is not inside the frame, or opacity is not between 0 and 1.
InvalidOperationException
The callback that received the canvas has returned, or source is a frame that is being drawn on or whose pixels are being accessed.
ObjectDisposedException
source no longer belongs to a live image.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.
UnsupportedImageFeatureException
source has a floating-point sample outside [0, 1] or that is not a number where it is read, which has no 16-bit color.
Remarks

See DrawingCanvas.DrawImage. The pixels around the region are not read.

DrawImage(ImageFrame, RectangleD, ImageSampling, double)

DrawingCanvas.cs

Draws the pixels of a frame of another image, stretched to a rectangle, read in a given way.

public void DrawImage(ImageFrame source, RectangleD destination, ImageSampling sampling, double opacity = 1d)
Parameters
source ImageFrame
The frame to draw.
destination RectangleD
The rectangle of the canvas the frame fills. A Rectangle of pixels converts implicitly.
sampling ImageSampling
How the image is read between the centers of its pixels.
opacity double
The opacity of the image, from 0 to 1.
Exceptions
ArgumentNullException
source is null.
ArgumentException
A coordinate is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate exceeds 16777216, sampling is not a defined ImageSampling, or opacity is not between 0 and 1.
InvalidOperationException
The callback that received the canvas has returned, or source is a frame that is being drawn on or whose pixels are being accessed.
ObjectDisposedException
source no longer belongs to a live image.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.
UnsupportedImageFeatureException
source has a floating-point sample outside [0, 1] or that is not a number where it is read, which has no 16-bit color.
Remarks

ImageSampling.Smooth reduces an image without skipping pixels (a thumbnail of a photograph), and ImageSampling.Nearest enlarges one with its pixels as squares. See DrawingCanvas.DrawImage.

DrawImage(ImageFrame, RectangleD, RectangleD, ImageSampling, double)

DrawingCanvas.cs

Draws a rectangle of a frame of another image that need not be made of whole pixels, stretched to a rectangle: drawImage of the HTML canvas with a source rectangle.

public void DrawImage(ImageFrame source, RectangleD sourceRegion, RectangleD destination, ImageSampling sampling, double opacity = 1d)
Parameters
source ImageFrame
The frame to draw.
sourceRegion RectangleD
The rectangle of the frame that is drawn, in its pixels.
destination RectangleD
The rectangle of the canvas the region fills.
sampling ImageSampling
How the image is read between the centers of its pixels.
opacity double
The opacity of the image, from 0 to 1.
Exceptions
ArgumentNullException
source is null.
ArgumentException
A coordinate is not a finite number.
ArgumentOutOfRangeException
sourceRegion is not inside the frame, the magnitude of a coordinate exceeds 16777216, sampling is not a defined ImageSampling, or opacity is not between 0 and 1.
InvalidOperationException
The callback that received the canvas has returned, or source is a frame that is being drawn on or whose pixels are being accessed.
ObjectDisposedException
source no longer belongs to a live image.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.
UnsupportedImageFeatureException
source has a floating-point sample outside [0, 1] or that is not a number where it is read, which has no 16-bit color.
Remarks

The pixels the rectangle touches are read, and the position each pixel of the canvas reads is brought into the rectangle, as browsers do: to [left + 1/2, right - 1/2] (the middle of the rectangle when it is narrower than a pixel) with ImageSampling.Bilinear, ImageSampling.Bicubic and ImageSampling.Smooth, so that the pixels around it weigh as little as they can, and to [left, right) with ImageSampling.Nearest. With a rectangle of whole pixels, the pixels are the ones of DrawingCanvas.DrawImage except near its edges, where this one does not extend the pixels of the edges but clamps the positions.

DrawImage(ImageFrame, RectangleD, double)

DrawingCanvas.cs

Draws the pixels of a frame of another image, stretched to a rectangle.

public void DrawImage(ImageFrame source, RectangleD destination, double opacity = 1d)
Parameters
source ImageFrame
The frame to draw.
destination RectangleD
The rectangle of the canvas the frame fills. A Rectangle of pixels converts implicitly.
opacity double
The opacity of the image, from 0 to 1.
Exceptions
ArgumentNullException
source is null.
ArgumentException
A coordinate is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate exceeds 16777216, or opacity is not between 0 and 1.
InvalidOperationException
The callback that received the canvas has returned, or source is a frame that is being drawn on or whose pixels are being accessed.
ObjectDisposedException
source no longer belongs to a live image.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.
UnsupportedImageFeatureException
source has a floating-point sample outside [0, 1] or that is not a number where it is read, which has no 16-bit color.
Remarks

The pixels are interpolated (see ImageBrush): an image that is made much smaller skips pixels. DrawingCanvas.DrawImage with ImageSampling.Smooth reads them all. See DrawingCanvas.DrawImage.

Fill overloads

Fill(Brush)

DrawingCanvas.cs

Paints the whole canvas.

public void Fill(Brush brush)
Parameters
brush Brush
The paint. A color converts implicitly.
Exceptions
ArgumentNullException
brush is null.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.

Fill(Brush, VectorPath, FillRule)

DrawingCanvas.cs

Paints the inside of a path. Open contours are closed by a straight segment.

public void Fill(Brush brush, VectorPath path, FillRule fillRule = FillRule.NonZero)
Parameters
brush Brush
The paint. A color converts implicitly.
path VectorPath
The path.
fillRule FillRule
The rule deciding what is inside when contours overlap.
Exceptions
ArgumentNullException
brush or path is null.
ArgumentOutOfRangeException
fillRule is not a defined FillRule.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.

FillCircle(Brush, PointD, double)

DrawingCanvas.cs

Paints a disk.

public void FillCircle(Brush brush, PointD center, double radius)

Parameters

brush Brush
The paint. A color converts implicitly.
center PointD
The center.
radius double
The radius. Must be zero or positive.

Exceptions

ArgumentNullException
brush is null.
ArgumentException
A coordinate or the radius is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate exceeds 16777216, or the radius is negative or exceeds 16777216.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.

FillClosedCurve(Brush, ReadOnlySpan<PointD>, double, FillRule)

DrawingCanvas.cs

Paints the inside of the closed curve that goes smoothly through consecutive points, and from the last one back to the first one.

public void FillClosedCurve(Brush brush, ReadOnlySpan<PointD> points, double tension = 0.5d, FillRule fillRule = FillRule.NonZero)

Parameters

brush Brush
The paint. A color converts implicitly.
points ReadOnlySpan<PointD>
The points the curve goes through. At least one is required.
tension double
How far the curve keeps its direction around each point, from 0 (a polygon) to 1; 0.5 is the Catmull-Rom spline.
fillRule FillRule
The rule deciding what is inside when the curve crosses itself.

Exceptions

ArgumentNullException
brush is null.
ArgumentException
points is empty, or a coordinate or tension is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate exceeds 16777216, tension is not between 0 and 1, the curve goes beyond the largest coordinate, or fillRule is not a defined FillRule.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.

Remarks

See VectorPathBuilder.AddClosedCurve.

FillEllipse(Brush, PointD, double, double)

DrawingCanvas.cs

Paints an ellipse whose axes are horizontal and vertical.

public void FillEllipse(Brush brush, PointD center, double radiusX, double radiusY)

Parameters

brush Brush
The paint. A color converts implicitly.
center PointD
The center.
radiusX double
The horizontal radius. Must be zero or positive.
radiusY double
The vertical radius. Must be zero or positive.

Exceptions

ArgumentNullException
brush is null.
ArgumentException
A coordinate or a radius is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate exceeds 16777216, or a radius is negative or exceeds 16777216.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.

FillGlyphs(Brush, Font, double, ReadOnlySpan<PositionedGlyph>, GlyphRunOptions?)

DrawingCanvas.cs

Fills a run of glyphs placed by the caller: the glyphs of a font at the positions a text shaper gives.

public void FillGlyphs(Brush brush, Font font, double size, ReadOnlySpan<PositionedGlyph> glyphs, GlyphRunOptions? options = null)

Parameters

brush Brush
The paint of the glyphs, and the color of the glyphs a font draws with its own colors where they ask for the color of the text.
font Font
The font.
size double
The size of the text: the length of an em, in units of the drawing.
glyphs ReadOnlySpan<PositionedGlyph>
The glyphs and their origins, in the coordinates of the drawing.
options GlyphRunOptions?
The synthesis, the palette and the cache, or null for none.

Exceptions

ArgumentNullException
brush or font is null.
ArgumentException
The size or a coordinate is not a finite number.
ArgumentOutOfRangeException
A glyph is not a glyph of the font, the size is negative, or the magnitude of a coordinate exceeds 16777216.
InvalidImageContentException
The outline or the display list of a glyph is malformed.
ImageResourceLimitException
The working storage would exceed the allocation limit.
InvalidOperationException
The callback that received the canvas has returned.
OperationCanceledException
The operation was canceled.

Remarks

Each glyph is filled on its own, over the ones before it. Under a transformation that keeps the axes (or swaps them), the origin of a glyph is moved to the nearest quarter of a pixel along the line and to the nearest pixel across it, as browsers do, and its coverage is computed once per position in a pixel when GlyphRunOptions.Cache keeps it: the pixels are the same with or without a cache. The glyphs a font draws with its own colors (COLR, sbix, CBDT) are drawn with them, from the palette of the options, then faded by the alpha of a solid brush and the opacity of the brush, as browsers draw an emoji in a translucent color; a variable font draws the glyphs of its instance (Font.WithVariations).

FillPie(Brush, PointD, double, double, double)

DrawingCanvas.cs

Paints a slice of a disk: the part between two radii and the arc that joins them.

public void FillPie(Brush brush, PointD center, double radius, double startAngle, double sweepAngle)

Parameters

brush Brush
The paint. A color converts implicitly.
center PointD
The center of the disk.
radius double
The radius. Must be zero or positive.
startAngle double
The angle of the first radius, in degrees from the positive x axis, clockwise on the image.
sweepAngle double
The angle of the slice, in degrees: positive to turn clockwise on the image, negative for the other way. Beyond 360 degrees either way, the slice is the whole disk.

Exceptions

ArgumentNullException
brush is null.
ArgumentException
A coordinate, the radius or an angle is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate exceeds 16777216, or the radius is negative or exceeds 16777216.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.

FillPolygon(Brush, ReadOnlySpan<PointD>, FillRule)

DrawingCanvas.cs

Paints the inside of the closed contour made of straight segments between consecutive points.

public void FillPolygon(Brush brush, ReadOnlySpan<PointD> points, FillRule fillRule = FillRule.NonZero)

Parameters

brush Brush
The paint. A color converts implicitly.
points ReadOnlySpan<PointD>
The vertices. At least one is required.
fillRule FillRule
The rule deciding what is inside when the contour crosses itself.

Exceptions

ArgumentNullException
brush is null.
ArgumentException
points is empty, or a coordinate is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate exceeds 16777216, or fillRule is not a defined FillRule.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.

FillRectangle(Brush, RectangleD)

DrawingCanvas.cs

Paints a rectangle.

public void FillRectangle(Brush brush, RectangleD rectangle)

Parameters

brush Brush
The paint. A color converts implicitly.
rectangle RectangleD
The rectangle. A Rectangle of pixels converts implicitly.

Exceptions

ArgumentNullException
brush is null.
ArgumentException
A coordinate is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate exceeds 16777216.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.

FillRoundedRectangle overloads

FillRoundedRectangle(Brush, RectangleD, CornerRadii)

DrawingCanvas.cs

Paints a rectangle whose corners are quarters of circles, each with its own radius.

public void FillRoundedRectangle(Brush brush, RectangleD rectangle, CornerRadii radii)
Parameters
brush Brush
The paint. A color converts implicitly.
rectangle RectangleD
The rectangle. A Rectangle of pixels converts implicitly.
radii CornerRadii
The radius of each corner; radii that do not fit are reduced together (see CornerRadii).
Exceptions
ArgumentNullException
brush is null.
ArgumentException
A coordinate is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate exceeds 16777216.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.

FillRoundedRectangle(Brush, RectangleD, double)

DrawingCanvas.cs

Paints a rectangle whose corners are quarters of a circle.

public void FillRoundedRectangle(Brush brush, RectangleD rectangle, double radius)
Parameters
brush Brush
The paint. A color converts implicitly.
rectangle RectangleD
The rectangle. A Rectangle of pixels converts implicitly.
radius double
The radius of the corners. Must be zero or positive; it is limited to half the shortest side of the rectangle.
Exceptions
ArgumentNullException
brush is null.
ArgumentException
A coordinate or the radius is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate exceeds 16777216, or the radius is negative or exceeds 16777216.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.

FillText overloads

FillText(Brush, TextLayout, VectorPath, TextPathOptions?)

DrawingCanvas.cs

Paints the glyphs of a text layout along a path.

public void FillText(Brush brush, TextLayout layout, VectorPath path, TextPathOptions? options = null)
Parameters
brush Brush
The paint of the spans that have none.
layout TextLayout
The text, laid out.
path VectorPath
The path the text follows: the horizontal axis of the layout, with its first baseline on it. A vertical layout follows it from the top of its lines, with the central baseline of its first line on it.
options TextPathOptions?
Where the text is on the path, or null for TextPathOptions.Default.
Exceptions
ArgumentNullException
brush, layout or path is null.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.
Remarks

The contours of the path are followed one after the other, in their direction; a path of one closed contour is followed around as many times as the text needs. Each cluster of the text (a character with its marks, a ligature) is placed as a whole: the middle of its advance is on the path, and it is turned to the direction of the path there. Glyphs are not bent, so they spread on the outside of a bend and overlap on the inside.

A path is measured as it is drawn: by its chords, within 1/16 of a pixel. A text on a path that draws nothing (no segment) is not drawn.

FillText(Brush, TextLayout, PointD)

DrawingCanvas.cs

Paints the glyphs of a text layout.

public void FillText(Brush brush, TextLayout layout, PointD origin)
Parameters
brush Brush
The paint.
layout TextLayout
The text, laid out.
origin PointD
The position of the top-left corner of the layout; the first baseline is TextLayout.Baseline below it, or on its right for a vertical layout.
Exceptions
ArgumentNullException
brush or layout is null.
ArgumentException
A coordinate is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate exceeds 16777216.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.
Remarks

The glyphs are one shape: where they overlap, the brush is applied once. The call allocates nothing once the working storage of the canvas has grown to the largest glyph. Glyphs are not snapped to the pixel grid.

FillText(Brush, string, Font, double, PointD)

DrawingCanvas.cs

Lays out a text on one line per line of the text and paints its glyphs.

public void FillText(Brush brush, string text, Font font, double size, PointD origin)
Parameters
brush Brush
The paint.
text string
The text.
font Font
The font.
size double
The size of the font, in pixels per em.
origin PointD
The position of the top-left corner of the text; the first baseline is half the line gap of the font plus its ascent below it.
Exceptions
ArgumentNullException
brush, text or font is null.
ArgumentException
A coordinate is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate exceeds 16777216, or size is not a positive number up to 65536.
InvalidOperationException
The callback that received the canvas has returned.
InvalidImageContentException
The data of a glyph of the text is malformed.
UnsupportedImageFeatureException
The outlines of the font use a feature that is not supported.
ImageResourceLimitException
The text exceeds a limit of the configuration of the font, or the working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.
Remarks

This overload creates a TextLayout each time it is called, which allocates. Create the layout once with TextLayout.Create to measure a text, or to draw it several times.

Filter overloads

Filter(ColorMatrix, DrawingAction)

DrawingCanvas.cs

Runs a callback whose drawings get new colors, as a whole, before they are drawn on the canvas: a photograph in gray levels, an icon in another color, a drawing that is dimmed.

public void Filter(ColorMatrix matrix, DrawingAction action)
Parameters
matrix ColorMatrix
The matrix.
action DrawingAction
The callback that draws. It must not be asynchronous and must not retain the canvas.
Exceptions
ArgumentNullException
matrix or action is null.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The layer or the working storage would exceed the allocation limit.
OperationCanceledException
The operation was canceled.
Remarks

The drawings are made on a layer (see DrawingCanvas.Layer). When the callback returns, each pixel of the layer gets the color matrix gives it from its own color and alpha, then the layer is drawn on the canvas. The matrix is applied to the stored samples of the layer, with straight alpha: 8-bit samples on a canvas of 8-bit colors, 16-bit samples otherwise (see ColorMatrix for the arithmetic).

The matrix applies to every pixel the clip can show, also those the callback did not draw on, which are transparent black: a matrix that gives an alpha to a transparent pixel (a constant in its last row) paints them.

Filter(Filter, DrawingAction)

DrawingCanvas.cs

Runs a callback whose drawings go through a filter, as a whole, before they are drawn on the canvas: the filter property of CSS.

public void Filter(Filter filter, DrawingAction action)
Parameters
filter Filter
The filter.
action DrawingAction
The callback that draws. It must not be asynchronous and must not retain the canvas.
Exceptions
ArgumentNullException
filter or action is null.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The layer or the working storage would exceed the allocation limit.
OperationCanceledException
The operation was canceled.
Remarks

The drawings are made on a layer (see DrawingCanvas.Layer) that holds the pixels the clip can show and, around them, as far as the filter moves what it filters (the reach of a blur, the offset and the blur of a shadow). When the callback returns, the layer goes through the filter (see Filter for the arithmetic), then it is drawn on the canvas. What a filter reads beyond the edges of the canvas is given by its edge mode: by default (FilterEdgeMode.Transparent), what the callback draws there, within the reach of the filter, and transparent pixels beyond it: a shape out of view casts its shadow on the canvas, and a shape that goes beyond an edge stays opaque there when it is blurred. The layer is then an image of its own, of the bounds of the clip with a margin of that reach (at most the largest side of the canvas, and while it has at most four times the pixels of the bounds of the clip and 65,536, within the limits of the image), and filling the whole canvas in it fills the canvas. The other edge modes extend the edges of the canvas instead.

A DropShadowFilter whose offset goes beyond that margin is cast from a window of its own: the bounds of the clip moved back by the offset, with the reach of the blur around them (within the same limits). The callback then runs twice, once on the layer of what the clip shows and once on that window (once, on the window, for a shadow alone): it must draw the same thing every time. Its cost depends on what the clip shows and on the blur, not on the length of the offset: a shape far out of view casts its shadow on the canvas.

The lengths of the filter are lengths of the drawing: under a transformation that scales the axes, they are scaled with them; under one that turns, skews or puts the drawing in perspective, the drawings and the filter are made on an image of the plane of the drawing, which is then drawn transformed (see DrawingCanvas.Transform).

Filter<TState>(ColorMatrix, TState, DrawingAction<TState>)

DrawingCanvas.cs

Runs a callback whose drawings get new colors before they are drawn on the canvas, passing caller state to avoid closure allocations.

public void Filter<TState>(ColorMatrix matrix, TState state, DrawingAction<TState> action) where TState : allows ref struct
Type parameters
TState
The type of the state.
Parameters
matrix ColorMatrix
The matrix.
state TState
The state passed to action.
action DrawingAction<TState>
The callback that draws. Use a static lambda to avoid allocations. It must not retain the canvas.
Exceptions
ArgumentNullException
matrix or action is null.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The layer or the working storage would exceed the allocation limit.
OperationCanceledException
The operation was canceled.
Remarks

See DrawingCanvas.Filter.

Filter<TState>(Filter, TState, DrawingAction<TState>)

DrawingCanvas.cs

Runs a callback whose drawings go through a filter before they are drawn, passing caller state to avoid closure allocations.

public void Filter<TState>(Filter filter, TState state, DrawingAction<TState> action) where TState : allows ref struct
Type parameters
TState
The type of the state.
Parameters
filter Filter
The filter.
state TState
The state passed to action.
action DrawingAction<TState>
The callback that draws. Use a static lambda to avoid allocations. It must not retain the canvas.
Exceptions
ArgumentNullException
filter or action is null.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The layer or the working storage would exceed the allocation limit.
OperationCanceledException
The operation was canceled.
Remarks

See DrawingCanvas.Filter.

FilterBackdrop(ColorMatrix)

DrawingCanvas.cs

Gives new colors to what is already drawn, where the clip lets a drawing through: the background of a dialog that is dimmed, a region that is shown in gray levels or inverted.

public void FilterBackdrop(ColorMatrix matrix)

Parameters

matrix ColorMatrix
The matrix.

Exceptions

ArgumentNullException
matrix is null.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.

Remarks

Each pixel of the canvas (of the layer, inside DrawingCanvas.Layer) is replaced by the color matrix gives it from its own color and alpha. Without a clip, every pixel is; inside DrawingCanvas.Clip, only the inside of the clip is, and a pixel on its edge in proportion to the area of it that is inside.

The matrix is applied to the stored samples of the pixels, at their precision (see ColorMatrix for the arithmetic and for the pixel formats without alpha or without colors). A pixel on the edge of a clip is replaced as a paint drawn with CompositeMode.Source replaces it. This is not a drawing: the blend mode and the operator of a brush do not apply, and neither does the opacity of a layer the canvas is not inside.

Flattening overloads

Flattening(double, DrawingAction)

DrawingCanvas.cs

Runs a callback whose curves are replaced by chords closer to them than the 1/16 of a pixel a canvas starts with.

public void Flattening(double tolerance, DrawingAction action)
Parameters
tolerance double
The largest distance between a curve and its chords, in pixels of the canvas: from 1/1024 to 1/16.
action DrawingAction
The callback that draws. It must not be asynchronous and must not retain the canvas.
Exceptions
ArgumentNullException
action is null.
ArgumentException
tolerance is not a finite number.
ArgumentOutOfRangeException
tolerance is less than 1/1024 or more than 1/16.
InvalidOperationException
The callback that received the canvas has returned.
OperationCanceledException
The operation was canceled.
Remarks

Curves, ellipses, arcs and the round joins and caps of the pens are drawn as chords that stay within a tolerance of them on the canvas. A finer tolerance makes antialiased edges closer to the curves, so that a shape drawn as different curves (a reference made of other elements) gives closer pixels, at the cost of more chords: halving the tolerance multiplies their number by about 1.4. This applies to the shapes, the strokes, the texts and the clips drawn while the callback runs, and to the tiles of the patterns they paint; the queries of a VectorPath keep the tolerance of 1/16.

Flattening<TState>(double, TState, DrawingAction<TState>)

DrawingCanvas.cs

Runs a callback whose curves are replaced by chords closer to them, passing caller state to avoid closure allocations.

public void Flattening<TState>(double tolerance, TState state, DrawingAction<TState> action) where TState : allows ref struct
Type parameters
TState
The type of the state.
Parameters
tolerance double
The largest distance between a curve and its chords, in pixels of the canvas: from 1/1024 to 1/16.
state TState
The state passed to action.
action DrawingAction<TState>
The callback that draws. Use a static lambda to avoid allocations. It must not retain the canvas.
Exceptions
ArgumentNullException
action is null.
ArgumentException
tolerance is not a finite number.
ArgumentOutOfRangeException
tolerance is less than 1/1024 or more than 1/16.
InvalidOperationException
The callback that received the canvas has returned.
OperationCanceledException
The operation was canceled.
Remarks

See DrawingCanvas.Flattening.

Group overloads

Group(GroupOptions, DrawingAction, DrawingAction?)

DrawingCanvas.cs

Runs a callback whose drawings are made in a group, which is composited as a whole when it ends.

public void Group(GroupOptions options, DrawingAction content, DrawingAction? mask = null)
Parameters
options GroupOptions
The attributes of the group.
content DrawingAction
The callback that draws the content of the group. It must not be asynchronous and must not retain the canvas.
mask DrawingAction?
The callback that draws the mask of the group, or null for none: the alpha, or the luminance (GroupOptions.MaskMode), of what it draws multiplies the alpha of the group.
Exceptions
ArgumentNullException
options or content is null.
ArgumentException
A coordinate of GroupOptions.Bounds is not a finite number.
ArgumentOutOfRangeException
The opacity is not between 0 and 1, or the blend mode or the mask mode is not defined.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The group or the working storage would exceed the allocation limit.
OperationCanceledException
The operation was canceled.
UnsupportedImageFeatureException
The group is not isolated and a floating-point sample of the canvas that it reads is outside [0, 1] or is not a number, and has no 16-bit color (see the remarks of DrawingCanvas).
Remarks

A group is a layer of 16-bit samples. An isolated group starts transparent, as a layer. A non-isolated group starts with the pixels under it, which its blend modes mix with; when it ends, those pixels are removed from its result (ISO 32000-2, 11.4.8), so that the group is composited once. A knockout group composites each element drawn with DrawingCanvas.KnockoutElement on its canvas with its initial backdrop: the element replaces what is under it in proportion to its shape; the other drawings of the group are composited as in any group. When the group ends, its alpha is multiplied by its opacity and by the values of its mask, then it is drawn on the canvas with its blend mode. A clip that is active when the group starts applies to the group as a whole.

The group starts with the pixels of what the call is made on: the canvas, or the layer the call is made in. Under a projective transformation, the group is drawn as an isolated layer.

Group<TState>(GroupOptions, TState, DrawingAction<TState>, DrawingAction<TState>?)

DrawingCanvas.cs

Runs a callback whose drawings are made in a group, which is composited as a whole when it ends, passing caller state to avoid closure allocations.

public void Group<TState>(GroupOptions options, TState state, DrawingAction<TState> content, DrawingAction<TState>? mask = null) where TState : allows ref struct
Type parameters
TState
The type of the state.
Parameters
options GroupOptions
The attributes of the group.
state TState
The state passed to content and mask.
content DrawingAction<TState>
The callback that draws the content of the group. Use a static lambda to avoid allocations. It must not retain the canvas.
mask DrawingAction<TState>?
The callback that draws the mask of the group, or null for none.
Exceptions
ArgumentNullException
options or content is null.
ArgumentException
A coordinate of GroupOptions.Bounds is not a finite number.
ArgumentOutOfRangeException
The opacity is not between 0 and 1, or the blend mode or the mask mode is not defined.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The group or the working storage would exceed the allocation limit.
OperationCanceledException
The operation was canceled.
UnsupportedImageFeatureException
The group is not isolated and a floating-point sample of the canvas that it reads is outside [0, 1] or is not a number, and has no 16-bit color (see the remarks of DrawingCanvas).
Remarks

See DrawingCanvas.Group.

HighPrecision overloads

HighPrecision(DrawingAction)

DrawingCanvas.cs

Runs a callback whose drawings are made with 16-bit samples, and rounded to the samples of the canvas once when it returns.

public void HighPrecision(DrawingAction action)
Parameters
action DrawingAction
The callback that draws. It must not be asynchronous and must not retain the canvas.
Exceptions
ArgumentNullException
action is null.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The copy or the working storage would exceed the allocation limit. The callback is not run.
OperationCanceledException
The operation was canceled.
Remarks

On a canvas of 8-bit samples, every draw call rounds its result to 8 bits: many translucent drawings on top of each other, layers inside layers and filters accumulate those roundings. Inside the callback, the drawings are made on a copy of the pixels the clip can show with 16-bit samples and alpha, which starts with the pixels of the canvas; layers started in it have 16-bit samples too. When the callback returns, the copy replaces the pixels as CompositeMode.Source does, through the clip: each color is rounded once. The coordinates do not change. On a canvas of 16-bit samples, the callback draws on the canvas itself.

The copy is rented when the callback starts and released when it returns: 8 bytes per pixel the clip can show, for each frame.

HighPrecision<TState>(TState, DrawingAction<TState>)

DrawingCanvas.cs

Runs a callback whose drawings are made with 16-bit samples, passing caller state to avoid closure allocations.

public void HighPrecision<TState>(TState state, DrawingAction<TState> action) where TState : allows ref struct
Type parameters
TState
The type of the state.
Parameters
state TState
The state passed to action.
action DrawingAction<TState>
The callback that draws. Use a static lambda to avoid allocations. It must not retain the canvas.
Exceptions
ArgumentNullException
action is null.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The copy or the working storage would exceed the allocation limit. The callback is not run.
OperationCanceledException
The operation was canceled.
Remarks

See DrawingCanvas.HighPrecision.

InnerShadow overloads

InnerShadow(Rgba64, PointD, double, DrawingAction)

DrawingCanvas.cs

Runs a callback whose drawings are drawn with a shadow inside them: the shadow cast on them by what is around them, for a shape that looks cut out or pressed in.

public void InnerShadow(Rgba64 color, PointD offset, double blur, DrawingAction action)
Parameters
color Rgba64
The color of the shadow, with straight alpha. An Rgba32 converts implicitly.
offset PointD
The distance the shadow is moved by: to the right and downward when positive, for a light that comes from the top left.
blur double
The standard deviation of the blur of the shadow, in pixels. Must be between 0 and 10000.
action DrawingAction
The callback that draws. It must not be asynchronous and must not retain the canvas.
Exceptions
ArgumentNullException
action is null.
ArgumentException
A coordinate of offset, or blur, is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate of offset exceeds 16777216, or blur is negative or exceeds 10000.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The layer or the working storage would exceed the allocation limit.
OperationCanceledException
The operation was canceled.
Remarks

The drawings are made on a layer (see DrawingCanvas.Layer). When the callback returns, the shadow is painted on the layer, where the drawings are, then the layer is drawn on the canvas. The shadow has the shape of everything the callback did not draw: its opacity is what is missing for the layer to be opaque, blurred by a Gaussian blur of standard deviation blur, moved by offset and multiplied by the alpha of color. It does not change the alpha of the drawings: nothing is painted outside them. A translucent drawing lacks opacity everywhere, and is shadowed all over: draw it opaque, in a layer that fades it, for a shadow along its edges only.

A drawing that goes beyond an edge of the canvas is taken to continue as it does on that edge. The time and the storage grow with the pixels the clip can show and with the blur, as for DrawingCanvas.Shadow.

InnerShadow<TState>(Rgba64, PointD, double, TState, DrawingAction<TState>)

DrawingCanvas.cs

Runs a callback whose drawings are drawn with a shadow inside them, passing caller state to avoid closure allocations.

public void InnerShadow<TState>(Rgba64 color, PointD offset, double blur, TState state, DrawingAction<TState> action) where TState : allows ref struct
Type parameters
TState
The type of the state.
Parameters
color Rgba64
The color of the shadow, with straight alpha. An Rgba32 converts implicitly.
offset PointD
The distance the shadow is moved by: to the right and downward when positive.
blur double
The standard deviation of the blur of the shadow, in pixels. Must be between 0 and 10000.
state TState
The state passed to action.
action DrawingAction<TState>
The callback that draws. Use a static lambda to avoid allocations. It must not retain the canvas.
Exceptions
ArgumentNullException
action is null.
ArgumentException
A coordinate of offset, or blur, is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate of offset exceeds 16777216, or blur is negative or exceeds 10000.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The layer or the working storage would exceed the allocation limit.
OperationCanceledException
The operation was canceled.
Remarks

See DrawingCanvas.InnerShadow.

KnockoutElement overloads

KnockoutElement(double, DrawingAction, DrawingAction?, MaskMode)

DrawingCanvas.cs

Runs a callback that draws an element of the knockout group whose canvas this is.

public void KnockoutElement(double opacity, DrawingAction content, DrawingAction? mask = null, MaskMode maskMode = MaskMode.Alpha)
Parameters
opacity double
The opacity of the element, from 0 to 1.
content DrawingAction
The callback that draws the element. It must not be asynchronous and must not retain the canvas.
mask DrawingAction?
The callback that draws the mask of the element, or null for none: its values multiply the opacity of the element.
maskMode MaskMode
How the values of the mask are read.
Exceptions
ArgumentNullException
content is null.
ArgumentOutOfRangeException
opacity is not between 0 and 1, or maskMode is not a defined MaskMode.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The element or the working storage would exceed the allocation limit.
OperationCanceledException
The operation was canceled.
UnsupportedImageFeatureException
Outside a knockout group, a floating-point sample of the canvas that it reads is outside [0, 1] or is not a number, and has no 16-bit color (see the remarks of DrawingCanvas).
Remarks

The callback draws the element with an opacity of 1, with its own blend modes; the element is composited with the initial backdrop of the group with opacity and the values of mask, and replaces what the group has in proportion to its shape (ISO 32000-2, 11.4.8): the alpha of what the callback draws counts as shape, so an element drawn with semi-transparent paints knocks out in proportion to their alpha.

On a canvas that is not the canvas of a knockout group (in a layer of the group, for instance), the element is a non-isolated group of its own, with that opacity and mask: it is drawn as if the callback drew with them.

KnockoutElement<TState>(double, TState, DrawingAction<TState>, DrawingAction<TState>?, MaskMode)

DrawingCanvas.cs

Runs a callback that draws an element of the knockout group whose canvas this is, passing caller state to avoid closure allocations.

public void KnockoutElement<TState>(double opacity, TState state, DrawingAction<TState> content, DrawingAction<TState>? mask = null, MaskMode maskMode = MaskMode.Alpha) where TState : allows ref struct
Type parameters
TState
The type of the state.
Parameters
opacity double
The opacity of the element, from 0 to 1.
state TState
The state passed to content and mask.
content DrawingAction<TState>
The callback that draws the element. Use a static lambda to avoid allocations. It must not retain the canvas.
mask DrawingAction<TState>?
The callback that draws the mask of the element, or null for none.
maskMode MaskMode
How the values of the mask are read.
Exceptions
ArgumentNullException
content is null.
ArgumentOutOfRangeException
opacity is not between 0 and 1, or maskMode is not a defined MaskMode.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The element or the working storage would exceed the allocation limit.
OperationCanceledException
The operation was canceled.
UnsupportedImageFeatureException
Outside a knockout group, a floating-point sample of the canvas that it reads is outside [0, 1] or is not a number, and has no 16-bit color (see the remarks of DrawingCanvas).
Remarks

See DrawingCanvas.KnockoutElement.

Layer overloads

Layer(RectangleD, double, DrawingAction, CompositeMode, BlendMode)

DrawingCanvas.cs

Runs a callback whose drawings are made on a transparent layer that holds the pixels of a rectangle only, which is then drawn on the canvas as a whole.

public void Layer(RectangleD bounds, double opacity, DrawingAction action, CompositeMode compositeMode = CompositeMode.SourceOver, BlendMode blendMode = BlendMode.Normal)
Parameters
bounds RectangleD
The rectangle the drawings of the layer are in, in the coordinates of the drawing.
opacity double
The opacity of the layer, from 0 (nothing is drawn; the callback still runs) to 1.
action DrawingAction
The callback that draws. It must not be asynchronous and must not retain the canvas.
compositeMode CompositeMode
The operator that combines the layer with the canvas.
blendMode BlendMode
The blend mode that mixes the colors of the layer with those of the canvas, before the operator.
Exceptions
ArgumentNullException
action is null.
ArgumentException
A coordinate of bounds is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate of bounds exceeds 16777216, opacity is not between 0 and 1, compositeMode is not a defined CompositeMode, or blendMode is not a defined BlendMode.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The layer or the working storage would exceed the allocation limit.
OperationCanceledException
The operation was canceled.
Remarks

The layer is drawn as the one of DrawingCanvas.Layer is, with the same pixels when the drawings are inside the rectangle, but it holds the pixels of the box of the rectangle on the canvas that the clip can show, instead of the pixels of the whole canvas: what is drawn outside them is not kept. The memory of the layer is the one of that box, rented when the layer starts and released when it ends, which suits a small group of drawings on a large canvas (an element of a page with an opacity). Its drawings are made by a canvas of their own, whose coordinates are those of this one: the callback receives it.

The opacity is a coverage of what the operator makes, as the edge of a shape is: a pixel gets o R + (1 - o) D, where R is the layer combined with the canvas D. With CompositeMode.SourceOver, it is the layer faded, then drawn; with the other operators, it is not the group opacity of CSS, which fades the layer, then combines it (CompositeMode.Plus at an opacity of 0.6 over an alpha of 0.6 gives 0.84 here, and 1 in CSS). The overload with a LayerOpacity gives that result with LayerOpacity.Group.

Under a projective transformation, the layer holds what the canvas can show, as any layer.

Layer(RectangleD, double, DrawingAction, CompositeMode, BlendMode, LayerOpacity)

DrawingCanvas.cs

Runs a callback whose drawings are made on a transparent layer that holds the pixels of a rectangle only, with an opacity that is a coverage or the group opacity of CSS.

public void Layer(RectangleD bounds, double opacity, DrawingAction action, CompositeMode compositeMode, BlendMode blendMode, LayerOpacity opacityMode)
Parameters
bounds RectangleD
The rectangle the drawings of the layer are in, in the coordinates of the drawing.
opacity double
The opacity of the layer, from 0 to 1.
action DrawingAction
The callback that draws. It must not be asynchronous and must not retain the canvas.
compositeMode CompositeMode
The operator that combines the layer with the canvas.
blendMode BlendMode
The blend mode that mixes the colors of the layer with those of the canvas, before the operator.
opacityMode LayerOpacity
How the opacity combines with the operator.
Exceptions
ArgumentNullException
action is null.
ArgumentException
A coordinate of bounds is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate of bounds exceeds 16777216, opacity is not between 0 and 1, compositeMode is not a defined CompositeMode, blendMode is not a defined BlendMode, or opacityMode is not a defined LayerOpacity.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The layer or the working storage would exceed the allocation limit.
OperationCanceledException
The operation was canceled.
Remarks

See DrawingCanvas.Layer and, for opacityMode, DrawingCanvas.Layer.

Layer(double, DrawingAction, CompositeMode, BlendMode)

DrawingCanvas.cs

Runs a callback whose drawings are made on a transparent layer, which is then drawn on the canvas as a whole: with an opacity, or with an operator.

public void Layer(double opacity, DrawingAction action, CompositeMode compositeMode = CompositeMode.SourceOver, BlendMode blendMode = BlendMode.Normal)
Parameters
opacity double
The opacity of the layer, from 0 (nothing is drawn; the callback still runs) to 1.
action DrawingAction
The callback that draws. It must not be asynchronous and must not retain the canvas.
compositeMode CompositeMode
The operator that combines the layer with the canvas.
blendMode BlendMode
The blend mode that mixes the colors of the layer with those of the canvas, before the operator: a drawing that multiplies or screens what is under it.
Exceptions
ArgumentNullException
action is null.
ArgumentOutOfRangeException
opacity is not between 0 and 1, compositeMode is not a defined CompositeMode, or blendMode is not a defined BlendMode.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The layer or the working storage would exceed the allocation limit.
OperationCanceledException
The operation was canceled.
Remarks

Shapes drawn one after the other with a translucent paint show through each other where they overlap. In a layer, they are drawn as they are, then the whole is made translucent: canvas.Layer(0.5, ...) fades a drawing without changing it. With a compositeMode, the whole drawing is combined with the canvas: a layer drawn with CompositeMode.DestinationIn keeps the canvas where the drawing is opaque (a mask made of several shapes, or of a text), and one drawn with CompositeMode.DestinationOut erases it there. With a blendMode, its colors are mixed with those of the canvas as those of a brush are (see BlendMode).

The layer is an image of the size of the canvas, transparent when the callback starts, with colors and alpha (8-bit samples on an 8-bit color canvas, 16-bit samples otherwise): a drawing of opaque colors on whole pixels is the same in a layer and on the canvas. Its pixels are the pixels of the canvas: the coordinates do not change. When the callback returns, the layer is drawn on the canvas (or on the layer it was started in) as an image is: its pixels are converted to the pixel format of the canvas, and the opacity multiplies the coverage, as that of DrawingCanvas.DrawImage does. When the callback fails, the layer is not drawn.

The opacity is a coverage of what the operator makes, as the edge of a shape is: a pixel gets o R + (1 - o) D, where R is the layer combined with the canvas D. With CompositeMode.SourceOver, it is the layer faded, then drawn; with the other operators, it is not the group opacity of CSS, which fades the layer, then combines it (CompositeMode.Plus at an opacity of 0.6 over an alpha of 0.6 gives 0.84 here, and 1 in CSS). The overload with a LayerOpacity gives that result with LayerOpacity.Group.

A clip that is active when the layer starts applies to the layer as a whole. The image of a layer is taken from the allocation scope of the image when a layer first starts at its depth, and kept until the drawing ends; a layer costs the clearing and the drawing of the pixels the clip can show: start a layer inside DrawingCanvas.Clip when it only covers a part of a large canvas.

Layer(double, DrawingAction, CompositeMode, BlendMode, LayerOpacity)

DrawingCanvas.cs

Runs a callback whose drawings are made on a transparent layer, which is then drawn on the canvas as a whole, with an opacity that is a coverage or the group opacity of CSS.

public void Layer(double opacity, DrawingAction action, CompositeMode compositeMode, BlendMode blendMode, LayerOpacity opacityMode)
Parameters
opacity double
The opacity of the layer, from 0 to 1.
action DrawingAction
The callback that draws. It must not be asynchronous and must not retain the canvas.
compositeMode CompositeMode
The operator that combines the layer with the canvas.
blendMode BlendMode
The blend mode that mixes the colors of the layer with those of the canvas, before the operator.
opacityMode LayerOpacity
How the opacity combines with the operator.
Exceptions
ArgumentNullException
action is null.
ArgumentOutOfRangeException
opacity is not between 0 and 1, compositeMode is not a defined CompositeMode, blendMode is not a defined BlendMode, or opacityMode is not a defined LayerOpacity.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The layer or the working storage would exceed the allocation limit.
OperationCanceledException
The operation was canceled.
Remarks

See DrawingCanvas.Layer. With LayerOpacity.Group, the alpha of each pixel of the layer is multiplied by the opacity (at the precision of the canvas, as the Brush.Opacity of a brush multiplies the alpha of its colors), then the layer is combined with the canvas: the group compositing of CSS. CompositeMode.Plus at an opacity of 0.6 over an alpha of 0.6 gives 1, and a mask (CompositeMode.DestinationIn) at an opacity of 0.5 keeps half of what it covers and nothing of what it does not cover, even at an opacity of 0. With CompositeMode.SourceOver, both modes are the same, pixel for pixel. No other layer is made.

Layer<TState>(RectangleD, double, TState, DrawingAction<TState>, CompositeMode, BlendMode)

DrawingCanvas.cs

Runs a callback whose drawings are made on a transparent layer that holds the pixels of a rectangle only, passing caller state to avoid closure allocations.

public void Layer<TState>(RectangleD bounds, double opacity, TState state, DrawingAction<TState> action, CompositeMode compositeMode = CompositeMode.SourceOver, BlendMode blendMode = BlendMode.Normal) where TState : allows ref struct
Type parameters
TState
The type of the state.
Parameters
bounds RectangleD
The rectangle the drawings of the layer are in, in the coordinates of the drawing.
opacity double
The opacity of the layer, from 0 (nothing is drawn; the callback still runs) to 1.
state TState
The state passed to action.
action DrawingAction<TState>
The callback that draws. Use a static lambda to avoid allocations. It must not retain the canvas.
compositeMode CompositeMode
The operator that combines the layer with the canvas.
blendMode BlendMode
The blend mode that mixes the colors of the layer with those of the canvas, before the operator.
Exceptions
ArgumentNullException
action is null.
ArgumentException
A coordinate of bounds is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate of bounds exceeds 16777216, opacity is not between 0 and 1, compositeMode is not a defined CompositeMode, or blendMode is not a defined BlendMode.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The layer or the working storage would exceed the allocation limit.
OperationCanceledException
The operation was canceled.
Remarks

See DrawingCanvas.Layer.

Layer<TState>(RectangleD, double, TState, DrawingAction<TState>, CompositeMode, BlendMode, LayerOpacity)

DrawingCanvas.cs

Runs a callback whose drawings are made on a transparent layer that holds the pixels of a rectangle only, with an opacity that is a coverage or the group opacity of CSS, passing caller state to avoid closure allocations.

public void Layer<TState>(RectangleD bounds, double opacity, TState state, DrawingAction<TState> action, CompositeMode compositeMode, BlendMode blendMode, LayerOpacity opacityMode) where TState : allows ref struct
Type parameters
TState
The type of the state.
Parameters
bounds RectangleD
The rectangle the drawings of the layer are in, in the coordinates of the drawing.
opacity double
The opacity of the layer, from 0 to 1.
state TState
The state passed to action.
action DrawingAction<TState>
The callback that draws. Use a static lambda to avoid allocations. It must not retain the canvas.
compositeMode CompositeMode
The operator that combines the layer with the canvas.
blendMode BlendMode
The blend mode that mixes the colors of the layer with those of the canvas, before the operator.
opacityMode LayerOpacity
How the opacity combines with the operator.
Exceptions
ArgumentNullException
action is null.
ArgumentException
A coordinate of bounds is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate of bounds exceeds 16777216, opacity is not between 0 and 1, compositeMode is not a defined CompositeMode, blendMode is not a defined BlendMode, or opacityMode is not a defined LayerOpacity.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The layer or the working storage would exceed the allocation limit.
OperationCanceledException
The operation was canceled.
Remarks

See DrawingCanvas.Layer.

Layer<TState>(double, TState, DrawingAction<TState>, CompositeMode, BlendMode)

DrawingCanvas.cs

Runs a callback whose drawings are made on a transparent layer, which is then drawn on the canvas as a whole, passing caller state to avoid closure allocations.

public void Layer<TState>(double opacity, TState state, DrawingAction<TState> action, CompositeMode compositeMode = CompositeMode.SourceOver, BlendMode blendMode = BlendMode.Normal) where TState : allows ref struct
Type parameters
TState
The type of the state.
Parameters
opacity double
The opacity of the layer, from 0 (nothing is drawn; the callback still runs) to 1.
state TState
The state passed to action.
action DrawingAction<TState>
The callback that draws. Use a static lambda to avoid allocations. It must not retain the canvas.
compositeMode CompositeMode
The operator that combines the layer with the canvas.
blendMode BlendMode
The blend mode that mixes the colors of the layer with those of the canvas, before the operator.
Exceptions
ArgumentNullException
action is null.
ArgumentOutOfRangeException
opacity is not between 0 and 1, compositeMode is not a defined CompositeMode, or blendMode is not a defined BlendMode.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The layer or the working storage would exceed the allocation limit.
OperationCanceledException
The operation was canceled.
Remarks

See DrawingCanvas.Layer.

Layer<TState>(double, TState, DrawingAction<TState>, CompositeMode, BlendMode, LayerOpacity)

DrawingCanvas.cs

Runs a callback whose drawings are made on a transparent layer, with an opacity that is a coverage or the group opacity of CSS, passing caller state to avoid closure allocations.

public void Layer<TState>(double opacity, TState state, DrawingAction<TState> action, CompositeMode compositeMode, BlendMode blendMode, LayerOpacity opacityMode) where TState : allows ref struct
Type parameters
TState
The type of the state.
Parameters
opacity double
The opacity of the layer, from 0 to 1.
state TState
The state passed to action.
action DrawingAction<TState>
The callback that draws. Use a static lambda to avoid allocations. It must not retain the canvas.
compositeMode CompositeMode
The operator that combines the layer with the canvas.
blendMode BlendMode
The blend mode that mixes the colors of the layer with those of the canvas, before the operator.
opacityMode LayerOpacity
How the opacity combines with the operator.
Exceptions
ArgumentNullException
action is null.
ArgumentOutOfRangeException
opacity is not between 0 and 1, compositeMode is not a defined CompositeMode, blendMode is not a defined BlendMode, or opacityMode is not a defined LayerOpacity.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The layer or the working storage would exceed the allocation limit.
OperationCanceledException
The operation was canceled.
Remarks

See DrawingCanvas.Layer.

Mask overloads

Mask(DrawingAction, DrawingAction, MaskMode)

DrawingCanvas.cs

Runs a callback whose drawings are kept only where a mask is: the drawings of another callback, by their opacity or by their luminance.

public void Mask(DrawingAction mask, DrawingAction content, MaskMode mode = MaskMode.Alpha)
Parameters
mask DrawingAction
The callback that draws the mask. It must not be asynchronous and must not retain the canvas.
content DrawingAction
The callback that draws what is masked. It must not be asynchronous and must not retain the canvas.
mode MaskMode
What the mask keeps the content by: its alpha, or its luminance.
Exceptions
ArgumentNullException
mask or content is null.
ArgumentOutOfRangeException
mode is not a defined MaskMode.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The layers or the working storage would exceed the allocation limit.
OperationCanceledException
The operation was canceled.
Remarks

What content draws is drawn on a layer (see DrawingCanvas.Layer), and what mask draws on a layer of its own. Each pixel of the content is then kept in proportion to the mask there, and the result is drawn on the canvas. With MaskMode.Alpha, the mask is the alpha of its drawings: a shape, a text or a gradient to a transparent color, whatever their colors. With MaskMode.Luminance, as in the masks of SVG, it is the luminance of their colors multiplied by their alpha: white keeps, black removes, and a gradient from white to black fades.

The luminance of a pixel of the mask is its Rec. 709 luma on the stored sample values, the gray level Grayscale gives it. The content is drawn first, then the mask; both callbacks run once. When a callback fails, nothing is drawn. A clip that is active when the mask starts applies to the result.

Mask<TState>(TState, DrawingAction<TState>, DrawingAction<TState>, MaskMode)

DrawingCanvas.cs

Runs a callback whose drawings are kept only where a mask is, passing caller state to both callbacks to avoid closure allocations.

public void Mask<TState>(TState state, DrawingAction<TState> mask, DrawingAction<TState> content, MaskMode mode = MaskMode.Alpha) where TState : allows ref struct
Type parameters
TState
The type of the state.
Parameters
state TState
The state passed to mask and to content.
mask DrawingAction<TState>
The callback that draws the mask. Use a static lambda to avoid allocations. It must not retain the canvas.
content DrawingAction<TState>
The callback that draws what is masked. Use a static lambda to avoid allocations. It must not retain the canvas.
mode MaskMode
What the mask keeps the content by: its alpha, or its luminance.
Exceptions
ArgumentNullException
mask or content is null.
ArgumentOutOfRangeException
mode is not a defined MaskMode.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The layers or the working storage would exceed the allocation limit.
OperationCanceledException
The operation was canceled.
Remarks

See DrawingCanvas.Mask.

PaintProfile overloads

PaintProfile(IccProfile, DrawingAction, IccColorTransformOptions?)

DrawingCanvas.cs

Runs a callback whose paint colors are colors of an ICC profile: they are converted to the color space of the image before they are painted.

public void PaintProfile(IccProfile profile, DrawingAction action, IccColorTransformOptions? options = null)
Parameters
profile IccProfile
The profile of the colors of the paints: an RGB profile.
action DrawingAction
The callback that draws. It must not be asynchronous and must not retain the canvas.
options IccColorTransformOptions?
The options of the conversion, or null for IccColorTransformOptions.Default. Its tone mapping is not used.
Exceptions
ArgumentNullException
profile or action is null.
InvalidImageContentException
A profile is malformed. The callback is not run.
UnsupportedImageFeatureException
profile is not an RGB profile, a profile is not supported in its role, the color space of the image is ambiguous or unknown, or its samples are high dynamic range ones (PQ, HLG), among which the light of the white of a paint is not chosen implicitly. The callback is not run.
InvalidOperationException
The callback that received the canvas has returned.
OperationCanceledException
The operation was canceled.
Remarks

Without this, the color of a paint is taken as sample values of the image, whatever its color space: the red (255, 0, 0) is the most saturated red of the image, which is not the same color on an sRGB image and on a Display P3 or an Adobe RGB one. Inside the callback, a color is a color of profile (IccProfile.Srgb for the colors of CSS, of a design tool or of Colors), and the image gets the samples that show that color: those of its own ICC profile (ImageMetadata.IccProfile), else of its CICP color description (ImageMetadata.Cicp), else of sRGB, for which the colors of IccProfile.Srgb are not changed.

The colors that are converted are those the caller gives: the color of a SolidBrush, the stops of a gradient, the color of a shadow and of DrawingCanvas.Clear, and the brushes of a text. A gradient that mixes its stops in linear light, in Oklab or in Oklch mixes the colors as they are given, then converts each color it obtains; one that mixes encoded values mixes the converted stops. A color outside the color space of the image is clipped, component by component. The alpha of a color is not converted.

What is already samples of an image is not converted: the images that are drawn (DrawingCanvas.DrawImage, ImageBrush: convert them with ImageProcessingExtensions.ConvertColorProfile first), the glyphs a font draws with its own colors, and the constants of a ColorMatrix. On a grayscale image, a color becomes the gray level that has its luminance, as a conversion to a gray profile gives it, and not the luma of its samples. The conversion is the one of IccColorTransform, in double precision: it uses the functions of the platform, and a sample within about 1e-12 of a rounding boundary can differ by one from a platform to another.

PaintProfile<TState>(IccProfile, TState, DrawingAction<TState>, IccColorTransformOptions?)

DrawingCanvas.cs

Runs a callback whose paint colors are colors of an ICC profile, passing caller state to avoid closure allocations.

public void PaintProfile<TState>(IccProfile profile, TState state, DrawingAction<TState> action, IccColorTransformOptions? options = null) where TState : allows ref struct
Type parameters
TState
The type of the state.
Parameters
profile IccProfile
The profile of the colors of the paints: an RGB profile.
state TState
The state passed to action.
action DrawingAction<TState>
The callback that draws. Use a static lambda to avoid allocations. It must not retain the canvas.
options IccColorTransformOptions?
The options of the conversion, or null for IccColorTransformOptions.Default.
Exceptions
ArgumentNullException
profile or action is null.
InvalidImageContentException
A profile is malformed. The callback is not run.
UnsupportedImageFeatureException
A profile is not supported in its role, or the color space of the image is unknown, ambiguous or of a high dynamic range. The callback is not run.
InvalidOperationException
The callback that received the canvas has returned.
OperationCanceledException
The operation was canceled.
Remarks

See DrawingCanvas.PaintProfile.

Shadow overloads

Shadow(Rgba64, PointD, double, DrawingAction)

DrawingCanvas.cs

Runs a callback whose drawings are drawn with their shadow: a drop shadow, or a glow without offset.

public void Shadow(Rgba64 color, PointD offset, double blur, DrawingAction action)
Parameters
color Rgba64
The color of the shadow, with straight alpha: black at a third of its opacity is a soft shadow. An Rgba32 converts implicitly.
offset PointD
The distance from the drawings to their shadow: to the right and downward when positive.
blur double
The standard deviation of the blur of the shadow, in pixels: 0 for a shadow with the edges of the drawings. Must be between 0 and 10000.
action DrawingAction
The callback that draws. It must not be asynchronous and must not retain the canvas.
Exceptions
ArgumentNullException
action is null.
ArgumentException
A coordinate of offset, or blur, is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate of offset exceeds 16777216, or blur is negative or exceeds 10000.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The layer or the working storage would exceed the allocation limit.
OperationCanceledException
The operation was canceled.
Remarks

The drawings are made on a layer (see DrawingCanvas.Layer). When the callback returns, the shadow of the layer is painted on the canvas, then the layer over it. The shadow has the shape of everything the callback drew, as a whole: its opacity is the alpha of the layer, blurred by a Gaussian blur of standard deviation blur (what CSS calls a blur radius is twice that), moved by offset and multiplied by the alpha of color.

A drawing that goes beyond an edge of the canvas is taken to continue as it does on that edge, so that its shadow does not fade there. A clip that is active when the callback starts applies to the drawings and to their shadow; what is drawn around it still casts its shadow in it. The time and the storage grow with the pixels the clip can show and with the blur: start the shadow of a small drawing inside DrawingCanvas.Clip, with room for the shadow.

Shadow<TState>(Rgba64, PointD, double, TState, DrawingAction<TState>)

DrawingCanvas.cs

Runs a callback whose drawings are drawn with their shadow, passing caller state to avoid closure allocations.

public void Shadow<TState>(Rgba64 color, PointD offset, double blur, TState state, DrawingAction<TState> action) where TState : allows ref struct
Type parameters
TState
The type of the state.
Parameters
color Rgba64
The color of the shadow, with straight alpha. An Rgba32 converts implicitly.
offset PointD
The distance from the drawings to their shadow: to the right and downward when positive.
blur double
The standard deviation of the blur of the shadow, in pixels. Must be between 0 and 10000.
state TState
The state passed to action.
action DrawingAction<TState>
The callback that draws. Use a static lambda to avoid allocations. It must not retain the canvas.
Exceptions
ArgumentNullException
action is null.
ArgumentException
A coordinate of offset, or blur, is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate of offset exceeds 16777216, or blur is negative or exceeds 10000.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The layer or the working storage would exceed the allocation limit.
OperationCanceledException
The operation was canceled.
Remarks

See DrawingCanvas.Shadow.

Stroke(Pen, VectorPath)

DrawingCanvas.cs

Paints the outline of a path.

public void Stroke(Pen pen, VectorPath path)

Parameters

pen Pen
The stroke.
path VectorPath
The path.

Exceptions

ArgumentNullException
pen or path is null.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.

StrokeArc(Pen, PointD, double, double, double)

DrawingCanvas.cs

Paints an arc of a circle, with the caps of the pen at both ends.

public void StrokeArc(Pen pen, PointD center, double radius, double startAngle, double sweepAngle)

Parameters

pen Pen
The stroke.
center PointD
The center of the circle.
radius double
The radius. Must be zero or positive.
startAngle double
The angle of the first point, in degrees from the positive x axis, clockwise on the image.
sweepAngle double
The angle of the arc, in degrees: positive to turn clockwise on the image, negative for the other way. Beyond 360 degrees either way, the arc is the whole circle.

Exceptions

ArgumentNullException
pen is null.
ArgumentException
A coordinate, the radius or an angle is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate exceeds 16777216, or the radius is negative or exceeds 16777216.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.

StrokeBezier overloads

StrokeBezier(Pen, PointD, PointD, PointD)

DrawingCanvas.cs

Paints a quadratic Bézier curve, with the caps of the pen at both ends.

public void StrokeBezier(Pen pen, PointD start, PointD control, PointD end)
Parameters
pen Pen
The stroke.
start PointD
The first point.
control PointD
The control point.
end PointD
The last point.
Exceptions
ArgumentNullException
pen is null.
ArgumentException
A coordinate is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate exceeds 16777216.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.

StrokeBezier(Pen, PointD, PointD, PointD, PointD)

DrawingCanvas.cs

Paints a cubic Bézier curve, with the caps of the pen at both ends.

public void StrokeBezier(Pen pen, PointD start, PointD control1, PointD control2, PointD end)
Parameters
pen Pen
The stroke.
start PointD
The first point.
control1 PointD
The first control point.
control2 PointD
The second control point.
end PointD
The last point.
Exceptions
ArgumentNullException
pen is null.
ArgumentException
A coordinate is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate exceeds 16777216.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.

StrokeCircle(Pen, PointD, double)

DrawingCanvas.cs

Paints the outline of a circle.

public void StrokeCircle(Pen pen, PointD center, double radius)

Parameters

pen Pen
The stroke.
center PointD
The center.
radius double
The radius. Must be zero or positive.

Exceptions

ArgumentNullException
pen is null.
ArgumentException
A coordinate or the radius is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate exceeds 16777216, or the radius is negative or exceeds 16777216.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.

StrokeClosedCurve(Pen, ReadOnlySpan<PointD>, double)

DrawingCanvas.cs

Paints the outline of the closed curve that goes smoothly through consecutive points, and from the last one back to the first one.

public void StrokeClosedCurve(Pen pen, ReadOnlySpan<PointD> points, double tension = 0.5d)

Parameters

pen Pen
The stroke.
points ReadOnlySpan<PointD>
The points the curve goes through. At least one is required.
tension double
How far the curve keeps its direction around each point, from 0 (straight segments) to 1; 0.5 is the Catmull-Rom spline.

Exceptions

ArgumentNullException
pen is null.
ArgumentException
points is empty, or a coordinate or tension is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate exceeds 16777216, tension is not between 0 and 1, or the curve goes beyond the largest coordinate.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.

Remarks

See VectorPathBuilder.AddClosedCurve.

StrokeCurve(Pen, ReadOnlySpan<PointD>, double)

DrawingCanvas.cs

Paints a curve that goes smoothly through consecutive points, with the caps of the pen at both ends: the line of a chart.

public void StrokeCurve(Pen pen, ReadOnlySpan<PointD> points, double tension = 0.5d)

Parameters

pen Pen
The stroke.
points ReadOnlySpan<PointD>
The points the curve goes through. At least one is required.
tension double
How far the curve keeps its direction around each point, from 0 (straight segments) to 1; 0.5 is the Catmull-Rom spline.

Exceptions

ArgumentNullException
pen is null.
ArgumentException
points is empty, or a coordinate or tension is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate exceeds 16777216, tension is not between 0 and 1, or the curve goes beyond the largest coordinate.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.

Remarks

The curve is the one of VectorPathBuilder.AddCurve: a cubic Bézier curve between each point and the next one, which has at each point the direction of the line between the points around it.

StrokeEllipse(Pen, PointD, double, double)

DrawingCanvas.cs

Paints the outline of an ellipse whose axes are horizontal and vertical.

public void StrokeEllipse(Pen pen, PointD center, double radiusX, double radiusY)

Parameters

pen Pen
The stroke.
center PointD
The center.
radiusX double
The horizontal radius. Must be zero or positive.
radiusY double
The vertical radius. Must be zero or positive.

Exceptions

ArgumentNullException
pen is null.
ArgumentException
A coordinate or a radius is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate exceeds 16777216, or a radius is negative or exceeds 16777216.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.

StrokeGlyphs(Pen, Font, double, ReadOnlySpan<PositionedGlyph>, GlyphRunOptions?)

DrawingCanvas.cs

Strokes the outlines of a run of glyphs placed by the caller, as one shape: strokeText of the HTML canvas.

public void StrokeGlyphs(Pen pen, Font font, double size, ReadOnlySpan<PositionedGlyph> glyphs, GlyphRunOptions? options = null)

Parameters

pen Pen
The pen.
font Font
The font.
size double
The size of the text: the length of an em, in units of the drawing.
glyphs ReadOnlySpan<PositionedGlyph>
The glyphs and their origins, in the coordinates of the drawing.
options GlyphRunOptions?
The synthesis, or null for none.

Exceptions

ArgumentNullException
pen or font is null.
ArgumentException
The size or a coordinate is not a finite number.
ArgumentOutOfRangeException
A glyph is not a glyph of the font, the size is negative, or the magnitude of a coordinate exceeds 16777216.
InvalidImageContentException
The outline of a glyph is malformed.
ImageResourceLimitException
The working storage would exceed the allocation limit.
InvalidOperationException
The callback that received the canvas has returned.
OperationCanceledException
The operation was canceled.

Remarks

A synthetic oblique shears the outlines; a synthetic bold does not widen the pen, as for DrawingCanvas.StrokeText. The glyphs a font draws with its own colors are stroked as their outlines.

StrokeLine(Pen, PointD, PointD)

DrawingCanvas.cs

Paints a straight line, with the caps of the pen at both ends.

public void StrokeLine(Pen pen, PointD start, PointD end)

Parameters

pen Pen
The stroke.
start PointD
The first point.
end PointD
The last point.

Exceptions

ArgumentNullException
pen is null.
ArgumentException
A coordinate is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate exceeds 16777216.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.

StrokePolygon(Pen, ReadOnlySpan<PointD>)

DrawingCanvas.cs

Paints the outline of the closed contour made of straight segments between consecutive points.

public void StrokePolygon(Pen pen, ReadOnlySpan<PointD> points)

Parameters

pen Pen
The stroke.
points ReadOnlySpan<PointD>
The vertices. At least one is required.

Exceptions

ArgumentNullException
pen is null.
ArgumentException
points is empty, or a coordinate is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate exceeds 16777216.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.

StrokePolyline(Pen, ReadOnlySpan<PointD>)

DrawingCanvas.cs

Paints the straight segments between consecutive points, with the caps of the pen at both ends.

public void StrokePolyline(Pen pen, ReadOnlySpan<PointD> points)

Parameters

pen Pen
The stroke.
points ReadOnlySpan<PointD>
The points. At least one is required.

Exceptions

ArgumentNullException
pen is null.
ArgumentException
points is empty, or a coordinate is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate exceeds 16777216.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.

StrokeRectangle(Pen, RectangleD)

DrawingCanvas.cs

Paints the outline of a rectangle. The stroke is centered on the sides of the rectangle.

public void StrokeRectangle(Pen pen, RectangleD rectangle)

Parameters

pen Pen
The stroke.
rectangle RectangleD
The rectangle. A Rectangle of pixels converts implicitly.

Exceptions

ArgumentNullException
pen is null.
ArgumentException
A coordinate is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate exceeds 16777216.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.

StrokeRoundedRectangle overloads

StrokeRoundedRectangle(Pen, RectangleD, CornerRadii)

DrawingCanvas.cs

Paints the outline of a rectangle whose corners are quarters of circles, each with its own radius. The stroke is centered on the outline.

public void StrokeRoundedRectangle(Pen pen, RectangleD rectangle, CornerRadii radii)
Parameters
pen Pen
The stroke.
rectangle RectangleD
The rectangle. A Rectangle of pixels converts implicitly.
radii CornerRadii
The radius of each corner; radii that do not fit are reduced together (see CornerRadii).
Exceptions
ArgumentNullException
pen is null.
ArgumentException
A coordinate is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate exceeds 16777216.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.

StrokeRoundedRectangle(Pen, RectangleD, double)

DrawingCanvas.cs

Paints the outline of a rectangle whose corners are quarters of a circle. The stroke is centered on the outline.

public void StrokeRoundedRectangle(Pen pen, RectangleD rectangle, double radius)
Parameters
pen Pen
The stroke.
rectangle RectangleD
The rectangle. A Rectangle of pixels converts implicitly.
radius double
The radius of the corners. Must be zero or positive; it is limited to half the shortest side of the rectangle.
Exceptions
ArgumentNullException
pen is null.
ArgumentException
A coordinate or the radius is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate exceeds 16777216, or the radius is negative or exceeds 16777216.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.

StrokeText overloads

StrokeText(Pen, TextLayout, VectorPath, TextPathOptions?)

DrawingCanvas.cs

Paints the outlines of the glyphs of a text layout along a path, with a pen.

public void StrokeText(Pen pen, TextLayout layout, VectorPath path, TextPathOptions? options = null)
Parameters
pen Pen
The stroke.
layout TextLayout
The text, laid out.
path VectorPath
The path the text follows: the horizontal axis of the layout, with its first baseline on it. A vertical layout follows it from the top of its lines, with the central baseline of its first line on it.
options TextPathOptions?
Where the text is on the path, or null for TextPathOptions.Default.
Exceptions
ArgumentNullException
pen, layout or path is null.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.
Remarks

The text is placed as by DrawingCanvas.FillText.

StrokeText(Pen, TextLayout, PointD)

DrawingCanvas.cs

Paints the outlines of the glyphs of a text layout with a pen.

public void StrokeText(Pen pen, TextLayout layout, PointD origin)
Parameters
pen Pen
The stroke.
layout TextLayout
The text, laid out.
origin PointD
The position of the top-left corner of the layout; the first baseline is TextLayout.Baseline below it, or on its right for a vertical layout.
Exceptions
ArgumentNullException
pen or layout is null.
ArgumentException
A coordinate is not a finite number.
ArgumentOutOfRangeException
The magnitude of a coordinate exceeds 16777216.
InvalidOperationException
The callback that received the canvas has returned.
ImageResourceLimitException
The working storage would exceed the allocation limit. No pixel is changed by this call.
OperationCanceledException
The operation was canceled.
Remarks

The strokes of all the outlines are one shape: where they overlap, the brush of the pen is applied once.

Transform overloads

Transform(AffineTransform, DrawingAction)

DrawingCanvas.cs

Runs a callback whose drawings are transformed: moved, turned, scaled, skewed or mirrored.

public void Transform(AffineTransform transform, DrawingAction action)
Parameters
transform AffineTransform
The transformation.
action DrawingAction
The callback that draws. It must not be asynchronous and must not retain the canvas.
Exceptions
ArgumentNullException
action is null.
ArgumentException
A coefficient of the transformation, combined with the one it starts in, is not a finite number.
InvalidOperationException
The callback that received the canvas has returned.
OperationCanceledException
The operation was canceled.
Remarks

Everything the callback draws is drawn as it would be without the transformation, then transformed: shapes, strokes (the pen is transformed with the path it strokes: a scaling makes it wider, and stretches its dashes, unless Pen.ScalesWithTransform is off: the pen then strokes the transformed path, as wide as it is), the gradients and the images of the brushes, images, texts with the paints of their spans and the glyphs a font draws with its own colors, the paths of the clips, and the offset and the blur of a shadow. This is what VectorPath.Transform does to a path, for any drawing: a text along a diagonal, or a drawing made for one size drawn at another.

A transformation started inside another one applies first, then the one around it. DrawingCanvas.Fill and DrawingCanvas.Clear still cover the whole canvas (the brush is transformed), and DrawingCanvas.Width and DrawingCanvas.Height stay those of the canvas. Curves are drawn at the size the transformation gives them: they stay smooth however they are enlarged. A transformation that flattens the plane to a line draws nothing.

The coordinates given to a draw call are validated as they are without transformation, and a coordinate that the transformation moves beyond 16777216 is rejected, before the call changes a pixel. A dashed stroke is cut into the dashes the canvas can show, as without transformation.

DrawingCanvas.Transform and DrawingCanvas.Transform draw in perspective.

Transform(ProjectiveTransform, DrawingAction)

DrawingCanvas.cs

Runs a callback whose drawings are transformed by a projective transformation: drawn on a plane seen in perspective.

public void Transform(ProjectiveTransform transform, DrawingAction action)
Parameters
transform ProjectiveTransform
The transformation.
action DrawingAction
The callback that draws. It must not be asynchronous and must not retain the canvas.
Exceptions
ArgumentNullException
action is null.
ArgumentException
A coefficient of the transformation, combined with the one it starts in, is not a finite number.
InvalidOperationException
The callback that received the canvas has returned.
OperationCanceledException
The operation was canceled.
Remarks

Everything DrawingCanvas.Transform transforms is transformed: shapes, strokes, the paints of the brushes, images, texts, clips and layers. A straight line stays straight, and what is further away is smaller. A point whose W is not positive (on the other side of the horizon of the plane, behind the viewer) has no image: a drawing that crosses the horizon is cut there, and the paint of a brush has no color beyond it. Nothing is rejected because of the transformation: what it sends beyond 16777216 is cut off.

Curves are cut into chords that stay within 1/16 of a pixel of them on the canvas, wherever the transformation enlarges a length by less than 65536. What has a size in the drawing (the blur and the offset of a shadow, a blur, the glyphs a font draws with its own colors) is drawn on an image of the plane of the drawing, then that image is drawn in perspective; that image has the resolution the transformation has where W is the one of the origin, and at most 4,194,304 pixels. A pattern is drawn at that resolution too.

An affine transformation (whose third column is (0, 0, 1)) draws what DrawingCanvas.Transform draws, bit for bit. Inside a transformation of space (DrawingCanvas.Transform), the transformation is combined as the transformation of space it is.

Transform(Transform3D, DrawingAction)

DrawingCanvas.cs

Runs a callback whose drawings are the plane z = 0 transformed by a transformation of space: turned in three dimensions and seen in perspective, as by the 3D transforms of CSS.

public void Transform(Transform3D transform, DrawingAction action)
Parameters
transform Transform3D
The transformation of space.
action DrawingAction
The callback that draws. It must not be asynchronous and must not retain the canvas.
Exceptions
ArgumentNullException
action is null.
ArgumentException
A coefficient of the transformation, combined with the one it starts in, is not a finite number.
InvalidOperationException
The callback that received the canvas has returned.
OperationCanceledException
The operation was canceled.
Remarks

The drawings are transformed by what the transformation does to the plane z = 0 (Transform3D.ToProjectiveTransform), as DrawingCanvas.Transform transforms them. A transformation started inside this one is combined with it in three dimensions (Transform3D.Then), whatever its kind: what an inner rotation does to z reaches an outer perspective, as the transforms of nested elements of CSS do.

Transform<TState>(AffineTransform, TState, DrawingAction<TState>)

DrawingCanvas.cs

Runs a callback whose drawings are transformed, passing caller state to avoid closure allocations.

public void Transform<TState>(AffineTransform transform, TState state, DrawingAction<TState> action) where TState : allows ref struct
Type parameters
TState
The type of the state.
Parameters
transform AffineTransform
The transformation.
state TState
The state passed to action.
action DrawingAction<TState>
The callback that draws. Use a static lambda to avoid allocations. It must not retain the canvas.
Exceptions
ArgumentNullException
action is null.
ArgumentException
A coefficient of the transformation, combined with the one it starts in, is not a finite number.
InvalidOperationException
The callback that received the canvas has returned.
OperationCanceledException
The operation was canceled.
Remarks

See DrawingCanvas.Transform.

Transform<TState>(ProjectiveTransform, TState, DrawingAction<TState>)

DrawingCanvas.cs

Runs a callback whose drawings are transformed by a projective transformation, passing caller state to avoid closure allocations.

public void Transform<TState>(ProjectiveTransform transform, TState state, DrawingAction<TState> action) where TState : allows ref struct
Type parameters
TState
The type of the state.
Parameters
transform ProjectiveTransform
The transformation.
state TState
The state passed to action.
action DrawingAction<TState>
The callback that draws. Use a static lambda to avoid allocations. It must not retain the canvas.
Exceptions
ArgumentNullException
action is null.
ArgumentException
A coefficient of the transformation, combined with the one it starts in, is not a finite number.
InvalidOperationException
The callback that received the canvas has returned.
OperationCanceledException
The operation was canceled.
Remarks

See DrawingCanvas.Transform.

Transform<TState>(Transform3D, TState, DrawingAction<TState>)

DrawingCanvas.cs

Runs a callback whose drawings are transformed by a transformation of space, passing caller state to avoid closure allocations.

public void Transform<TState>(Transform3D transform, TState state, DrawingAction<TState> action) where TState : allows ref struct
Type parameters
TState
The type of the state.
Parameters
transform Transform3D
The transformation of space.
state TState
The state passed to action.
action DrawingAction<TState>
The callback that draws. Use a static lambda to avoid allocations. It must not retain the canvas.
Exceptions
ArgumentNullException
action is null.
ArgumentException
A coefficient of the transformation, combined with the one it starts in, is not a finite number.
InvalidOperationException
The callback that received the canvas has returned.
OperationCanceledException
The operation was canceled.
Remarks

See DrawingCanvas.Transform.