CanvasAnimatedControl uses a CanvasSwapChain and CanvasSwapChainPanel for displaying graphics. The swap chain is automatically resized and recreated as necessary.

The control provides a game-style update and draw loop. This game loop runs on a dedicated thread. This means that the game loop and XAML's UI thread cannot block each other, ensuring that XAML UI elements remain responsive regardless of what the game loop is doing (and vice versa). However, it does require that care is taken when accessing data shared between the UI thread and the game loop thread.

When using CanvasAnimatedControl from managed code, care must be taken to avoid memory leaks due to reference count cycles. See Avoiding memory leaks for more information.

The control has five events that can be subscribed to:

CreateResources

This is raised when a new device is created and is the appropriate place to start loading bitmaps from disk and so on.

This event is raised on the UI thread.

GameLoopStarting

This is raised just before the game loop starts running. Applications can hook this to perform any initialization that must happen on the game loop thread. For example, CreateCoreIndependentInputSource(CoreInputDeviceTypes) must be called from the thread that will process the input events raised by the CoreIndependentInputSource.

This event is raised on the game loop thread.

Update

This tells the app to update animations, game logic, simulations etc. Update will only ever be raised after CreateResources, including any tracked asynchronous actions, has completed. See this article for more advanced asynchronous loading scenarios.

Depending on the value of IsFixedTimeStep, Update may be raised multiple times between each Draw event. See below for more details.

This event is raised on the game loop thread.

Draw

This tells the app to draw the contents of the control, using CanvasDrawEventArgs.DrawingSession. The control is been cleared to ClearColor before the Draw event is raised.

This event will only ever be raised after at least one Update has been completed. However, it may be raised multiple times in succession without an Update if the control is resized or the ClearColor property is modified.

This event is raised on the game loop thread.

GameLoopStopped

This is raised just after the game loop has stopped, and just before the game loop thread exits. Applications can hook this to perform any deinitialization that must happen on the game loop thread, such as unregistering event handlers on a CoreIndependentInputSource.

This event is raised on the game loop thread.

Game Loop

Each iteration of the game loop:

• raises some number of Update events
• raises one Draw event

The IsFixedTimeStep property controls how often the Update event is raised. This is a boolean value, and when set to true we say that the control is running with "fixed timing". When set to false it is running with "variable timing".

Defaults

IsFixedTimeStep

true

TargetElapsedTime

16.6ms (60 fps)

Paused

false

Fixed Timing

When IsFixedTimeStep is set to true, the control is running in fixed timing mode. This mode is particularly useful for games since it provides a deterministic elapsed time between updates, providing consistency in game simulation regardless of actual display framerate.

When running in fixed timing mode mode, the Update event is raised at a fixed rate, controled by the TargetElapsedTime property. For example, if TargetElapsedTime is set to its default value of 16.6ms, Update will be raised 60 times a second. There are several different scenarios depending on how long the Update and Draw handlers take to complete:

The simplest situation is that the total time spent in Update + Draw is exactly 1/60 of a second. In this case the control will raise Update, then raise Draw, then look at the clock and notice it is time for another Update, then Draw, and so on. Simple!

What if Update + Draw takes less than 1/60 of a second? Also simple. Here the control raises Update, then Draw, then looks at the clock, notices there is some time left over, so waits until it is time to raise Update again.

What if Update + Draw takes longer than 1/60 of a second? This is where things get complicated. There are many reasons why this could happen:

1. The computer might be slightly too slow to run the at the desired speed.
2. Or the computer might be way too slow to run the game at the desired speed!
3. The computer might be basically fast enough, but this particular frame might have taken an unusually long time for some reason. Perhaps there were too many explosions on screen, or there was a garbage collection.
4. The app could have been paused in the debugger.

• CanvasTimingInformation.IsRunningSlowly to true.
• Raises Update extra times (without calling Draw) until it catches up.
• If things are getting ridiculous and too many Updates are required to catch up, it just gives up.

Variable Timing

When IsFixedTimeStep is set to false, the control is running in variable timing mode. In this mode one, and only one, Update event is always raised before each Draw event. The app can determine how much time has passed between Update events by examining the CanvasTimingInformation available through the event args.

Paused behavior

When the Paused property is set to true, the control will stop raising Update events. However, when the control is resized or the clear color has changed, the Draw event will be raised to ensure that the display has been updated accordingly.

Pointer Input

The recommended way to receive pointer input events for a CanvasAnimatedControl is to use the standard XAML events, such as UIElement.PointerPressed.

These events are raised on the UI thread, so they may be raised concurrently with any of the game loop thread events (such as Update, Draw and so on). Care must be taken to ensure that access to any shared data structures is synchronized.

One strategy for handling this is to use RunOnGameLoopThreadAsync(DispatchedHandler) to execute code on the game loop thread. For example:

private void animatedControl_PointerPressed(object sender, PointerRoutedEventArgs e)
{
    var position = e.GetCurrentPoint(animatedControl).Position;
    var action = animatedControl.RunOnGameLoopThreadAsync(() =>
    {
        HandlePointerPressed(position);
    });
}

• KeyboardInputExample.xaml.cs
• GameOfLife.xaml.cs

For more advanced input handling, CanvasAnimatedControl provides CreateCoreIndependentInputSource(CoreInputDeviceTypes). This allows input to be processed on any thread (including the game loop thread). This gives the app finer control over input processing.

Keyboard Input

The simplest way to receive keyboard input events is to subscribe to CoreWindow's KeyDown and KeyUp events. The handlers for these events will be called on the UI thread, so if these need to access data that is also accessed by the game loop thread some kind of synchronization is required.

One possible approach here is to use RunOnGameLoopThreadAsync(DispatchedHandler) to execute code on the game loop thread. The gotcha here is that the KeyEventArgs is not agile and so should not be accessed from the game loop thead. Although this will work, it may have surprising performance effects since method calls / property accesses on the KeyEventArgs object could involving dispatching back to the UI thread!

Instead, process or extract the data from KeyEventArgs that needs to be accessed on the UI thread. Example:

// Register for keyboard events in the loaded handler...
private void PageLoaded(object sender, RoutedEventArgs e)
{
    Window.Current.CoreWindow.KeyDown += KeyDown_UIThread;
}

// Don't forget to unregister in unloaded!
private void PageUnloaded(object sender, RoutedEventArgs e)
{
    Window.Current.CoreWindow.KeyDown -= KeyDown_UIThread;
}

// The KeyDown handler runs on the UI thread...
private async void KeyDown_UIThread(CoreWindow sender, KeyEventArgs args)
{
    args.Handled = true;

    // extract the data from the args before marshaling it to the
    // game loop thread
    var virtualKey = args.VirtualKey;

    var action = animatedControl.RunOnGameLoopThreadAsync(() => KeyDown_GameLoopThread(virtualKey));
}

private void KeyDown_GameLoopThread(VirtualKey virtualKey)
{
    // ...
}

A more complete example can be found in the KeyboardInputExample in ExampleGallery.

Threading Considerations

CanvasAnimatedControl runs its game loop on a dedicated thread. This thread is started in response to the control's Loaded event, and stopped in response to the control's Unloaded event.

The CreateResources event runs on the UI thread. The other events - GameLoopStarting, Update, Draw and GameLoopStopped all run on the game loop thread. The control ensures that it does not raise any events on the game loop thread while CreateResources is running on the UI thread.

Arbitrary code can be scheduled to run on the game loop thread using RunOnGameLoopThreadAsync(DispatchedHandler). Work scheduled with this method will only run after CreateResources has completed.

The following diagram shows how the UI thread and game loop thread are synchronized:

When the control is first loaded the game loop thread is created. The control will not raise its own Loaded event until the game loop thread has finished raising the GameLoopStarting event. The app's Loaded event handlers will never run at the same time as the GameLoopStarting event.

The game loop thread waits until the CreateResources process has completed (included any asynchronous resource creation tasks) before starting the dispatcher.

While the dispatcher is running, it raises Update / Draw events as appropriate and runs RunOnGameLoopThread actions. If a CoreIndependentInputSource has been created on this thread then its events are dispatched through the dispatcher.

When the control is unloaded the game loop thread is shutdown. The game loop thread raises the GameLoopStopped event after the dispatcher has been stopped. The control will not raise its own Unloaded event until after the GameLoopStopped event has completed. The app's Unloaded event handlers will never run at the same time as the GameLoopStopped event.

Reference