Click or drag to resize
CanvasCachedGeometry Class
Cached geometries are a means of improving drawing performance of complicated geometry.
Inheritance Hierarchy
SystemObject
  Microsoft.Graphics.Canvas.GeometryCanvasCachedGeometry

Namespace:  Microsoft.Graphics.Canvas.Geometry
Assembly:  Microsoft.Graphics.Canvas (in Microsoft.Graphics.Canvas.dll) Version: 0.0.0.0
Syntax
C#
public sealed class CanvasCachedGeometry : IDisposable

The CanvasCachedGeometry type exposes the following members.

Properties
  NameDescription
Public propertyDevice
Gets the device associated with this CanvasCachedGeometry.
Top
Methods
  NameDescription
Public methodStatic memberCreateFill(CanvasGeometry)
Creates a new, cached version of the fill of a geometry.
Public methodStatic memberCreateFill(CanvasGeometry, Single)
Creates a new, cached version of the fill of a geometry.
Public methodStatic memberCreateStroke(CanvasGeometry, Single)
Creates a new, cached version of the stroke of a geometry with the specified stroke width.
Public methodStatic memberCreateStroke(CanvasGeometry, Single, CanvasStrokeStyle)
Creates a new, cached version of the stroke of a geometry with the specified stroke width and stroke style.
Public methodStatic memberCreateStroke(CanvasGeometry, Single, CanvasStrokeStyle, Single)
Creates a new, cached version of the stroke of a geometry with the specified stroke width and stroke style.
Public methodDispose
Releases all resources used by the CanvasCachedGeometry.
Top
Remarks

Cached geometries are slightly different from normal geometries. They are stored in a GPU hardware optimized format that doesn't allow operations like Widen or CombineWith. They can only be used for drawing.

Sometimes, CanvasCachedGeometry are more performance-costly to create than CanvasGeometry. However, it is always faster to draw CanvasCachedGeometry. Therefore, the best way to use them is not to create them every frame! Moreover, it's not suitable for cases where the geometry is drawn only once. Rather, use cached geometry for cases where it makes sense to pay the one-time, up-front caching cost so that it can be drawn cheaply many times. Create cached geometries when your app is loading its resources, and draw them in your draw routine.

Cached geometries are created and drawn in the following way:

CanvasCachedGeometry cachedGeometry;

void myWidget_CreateResources(CanvasControl sender, object args)
{
    ...
      CanvasGeometry geometry = CanvasGeometry.CreateRectangle(sender, 1, 1, 10, 10);
      cachedGeometry = CanvasCachedGeometry.CreateFill(geometry);
}

void myWidget_Draw(CanvasControl sender, CanvasDrawEventArgs args)
{
    args.DrawingSession.DrawCachedGeometry(cachedGeometry, Colors.Blue);
}

Cached geometries, like any resource, induce memory cost. Use them if geometry performance is expected to be a problem.

When a geometry is cached, it cannot contain curves. All the curved parts are turned into roughly equivalent, short, straight edges. This is called 'flattening'. Of course, this exact same operation occurs, internally, in Direct2D during Fill/Draw for CanvasGeometry; the straight edges are simply too small to see.

The flattening for cached geometry either explicitly or implicitly considers a 'flattening tolerance'. A flattening tolerance is a threshold at which a part of a curve is turned into a straight edge. A smaller tolerance produces a more accurate result, at the expense of performance and memory cost. A value of CanvasGeometry.DefaultFlatteningTolerance works for many common situations.

Cached geometries are associated with the device of the geometry that was used to create them.

While creating a cached geometry, if the source geometry extends outside of [-524,287, 524,287] DIPs along any axis, then the cached geometry may be clipped to those bounds. This clipping will be visible even if the cached geometry is later drawn scaled down to fit within the bounds.

To draw massive cached geometries with no clipping, ensure that the coordinate space of the source geometry fits within the above bounds, and use a scale transform on the drawing session to scale it up.

For more information about the Direct2D implementation of cached geometries used by Win2D, see Geometry Realizations Overview.

When using Direct2D interop, this Win2D class corresponds to the Direct2D interface ID2D1GeometryRealization.

See Also