Click or drag to resize
CanvasVirtualControl Class
XAML control providing immediate mode 2D rendering to a virtualized surface.
Inheritance Hierarchy
SystemObject
  Windows.UI.Xaml.ControlsUserControl
    Microsoft.Graphics.Canvas.UI.XamlCanvasVirtualControl

Namespace:  Microsoft.Graphics.Canvas.UI.Xaml
Assembly:  Microsoft.Graphics.Canvas (in Microsoft.Graphics.Canvas.dll) Version: 0.0.0.0
Syntax
C#
public sealed class CanvasVirtualControl : UserControl, 
	IAnimationObject, IVisualElement, ICanvasResourceCreatorWithDpi, ICanvasResourceCreator

The CanvasVirtualControl type exposes the following members.

Constructors
  NameDescription
Public methodCanvasVirtualControl
Initializes a new instance of the CanvasVirtualControl class.
Top
Properties
  NameDescription
Public propertyClearColor
The color that the control is cleared to when CreateDrawingSession is called.
Public propertyCustomDevice
Gets or sets an application-chosen device for this control.
Public propertyDevice
Gets the underlying device used by this control.
Public propertyDpi
Gets the current dots-per-inch (DPI) of this control.
Public propertyDpiScale
Gets or sets a scaling factor applied to this control's Dpi.
Public propertyForceSoftwareRenderer
Gets or sets the whether the devices that this control creates will be forced to software rendering.
Public propertyReadyToDraw
Gets whether the control is in a state where it is ready to draw.
Public propertySize
Gets the current size of the control, in device independent pixels (DIPs).
Public propertyUseSharedDevice
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
  NameDescription
Public methodConvertDipsToPixels
Converts units from device independent pixels (DIPs) to physical pixels based on the current DPI of this control.
Public methodConvertPixelsToDips
Converts units from physical pixels to device independent pixels (DIPs) based on the current DPI of this control.
Public methodCreateDrawingSession
Returns a new drawing session for updating a region of the control.
Public methodInvalidate
Marks the entire control as needing to be redrawn.
Public methodInvalidate(Rect)
Marks a region of the control as needing to be redrawn.
Public methodRemoveFromVisualTree
Removes the control from the last FrameworkElement it was parented to.
Public methodResumeDrawingSession
Resumes a previously suspended drawing session.
Public methodSuspendDrawingSession
Suspends a drawing session so that it may be resumed on another thread.
Top
Events
  NameDescription
Public eventCreateResources
Hook this event to create any resources needed for your drawing.
Public eventRegionsInvalidated
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:

C#
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
<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:

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

See Also