CanvasVirtualControl Class

XAML control providing immediate mode 2D rendering to a virtualized surface.

Inheritance Hierarchy

System.Object
Windows.UI.Xaml.Controls.UserControl
Microsoft.Graphics.Canvas.UI.Xaml.CanvasVirtualControl

Namespace: Microsoft.Graphics.Canvas.UI.Xaml
Assembly: Microsoft.Graphics.Canvas (in Microsoft.Graphics.Canvas.dll) Version: 0.0.0.0

Syntax

Copy

public sealed class CanvasVirtualControl : UserControl, 
	IAnimationObject, IVisualElement, ICanvasResourceCreatorWithDpi, ICanvasResourceCreator

The CanvasVirtualControl type exposes the following members.

Constructors

	Name	Description
	CanvasVirtualControl	Initializes a new instance of the CanvasVirtualControl class.

Top

Properties

	Name	Description
	ClearColor	The color that the control is cleared to when CreateDrawingSession is called.
	CustomDevice	Gets or sets an application-chosen device for this control.
	Device	Gets the underlying device used by this control.
	Dpi	Gets the current dots-per-inch (DPI) of this control.
	DpiScale	Gets or sets a scaling factor applied to this control's Dpi.
	ForceSoftwareRenderer	Gets or sets the whether the devices that this control creates will be forced to software rendering.
	ReadyToDraw	Gets whether the control is in a state where it is ready to draw.
	Size	Gets the current size of the control, in device independent pixels (DIPs).
	UseSharedDevice	Gets or sets whether this control should create a new device each time, or use a device which may common between other controls.

Top

Methods

	Name	Description
	ConvertDipsToPixels	Converts units from device independent pixels (DIPs) to physical pixels based on the current DPI of this control.
	ConvertPixelsToDips	Converts units from physical pixels to device independent pixels (DIPs) based on the current DPI of this control.
	CreateDrawingSession	Returns a new drawing session for updating a region of the control.
	Invalidate()	Marks the entire control as needing to be redrawn.
	Invalidate(Rect)	Marks a region of the control as needing to be redrawn.
	RemoveFromVisualTree	Removes the control from the last FrameworkElement it was parented to.
	ResumeDrawingSession	Resumes a previously suspended drawing session.
	SuspendDrawingSession	Suspends a drawing session so that it may be resumed on another thread.

Top

Events

	Name	Description
	CreateResources	Hook this event to create any resources needed for your drawing.
	RegionsInvalidated	Occurs when a region of the control needs redrawing.

Top

Remarks

Use CanvasVirtualControl if:

the image you are drawing is very large
you don't want to spend time drawing non-visible parts of the image
you don't want the entire image to be resident in memory
or you want to control what thread the drawing happens on

CanvasVirtualControl is built on top of CanvasVirtualImageSource. The image is virtualized; this means that the entire image does not need to be resident in memory at any one time. Instead, the OS keeps track of which regions of the image are valid, and which regions are invalid. When an invalid region needs to be shown on screen the RegionsInvalidated event is raised to give the app an opportunity to redraw the contents.

From within the RegionsInvalidated event handler, use CreateDrawingSession(Rect) to redraw:

Copy

void OnRegionsInvalidated(CanvasVirtualControl sender, CanvasRegionsInvalidatedEventArgs args)
{
    foreach (var region in args.InvalidatedRegions)
    {
        using (var ds = sender.CreateDrawingSession(region))
        {
            // draw the region
        }
    }
}

CanvasVirtualControl works well when it is placed within a XAML ScrollViewer:

XAML

Copy

<ScrollViewer>
  <canvas:CanvasVirtualControl Width="10000" Height="10000" RegionsInvalidated="OnRegionsInvalidated" />
</ScrollViewer>

When a CanvasVirtualControl's size changes the current contents of the control is not invalidated. In order to make the contents invalidate on resize, add a SizeChanged event handler and call Invalidate() from it:

Copy

void VirtualControl_SizeChanged(object sender, SizeChangedEventArgs e)
{
    VirtualControl.Invalidate();
}

Reference

Microsoft.Graphics.Canvas.UI.Xaml Namespace