David CoulterandAndy De George
674b773578
* Links: .NET Desktop - framework\wpf * Apply suggestions from code review Co-authored-by: Andy De George <[email protected]>
5.0 KiB
title, ms.date, dev_langs, helpviewer_keywords, ms.assetid
| title | ms.date | dev_langs | helpviewer_keywords | ms.assetid | ||||
|---|---|---|---|---|---|---|---|---|
| How to: Render on a Per Frame Interval Using CompositionTarget | 03/30/2017 |
|
|
701246cd-66b7-4d69-ada9-17b3b433d95d |
How to: Render on a Per Frame Interval Using CompositionTarget
The [!INCLUDETLA2#tla_winclient] animation engine provides many features for creating frame-based animation. However, there are application scenarios in which you need finer-grained control over rendering on a per frame basis. The xref:System.Windows.Media.CompositionTarget object provides the ability to create custom animations based on a per-frame callback.
xref:System.Windows.Media.CompositionTarget is a static class which represents the display surface on which your application is being drawn. The xref:System.Windows.Media.CompositionTarget.Rendering event is raised each time the application's scene is drawn. The rendering frame rate is the number of times the scene is drawn per second.
Note
For a complete code sample using xref:System.Windows.Media.CompositionTarget, see Using the CompositionTarget Sample.
Example
The xref:System.Windows.Media.CompositionTarget.Rendering event fires during the [!INCLUDETLA2#tla_winclient] rendering process. The following example shows how you register an xref:System.EventHandler delegate to the static xref:System.Windows.Media.CompositionTarget.Rendering method on xref:System.Windows.Media.CompositionTarget.
[!code-csharpCompositionTargetSample#CompositionTarget1] [!code-vbCompositionTargetSample#CompositionTarget1]
You can use your rendering event handler method to create custom drawing content. This event handler method gets called once per frame. Each time that [!INCLUDETLA2#tla_winclient] marshals the persisted rendering data in the visual tree across to the composition scene graph, your event handler method is called. In addition, if changes to the visual tree force updates to the composition scene graph, your event handler method is also called. Note that your event handler method is called after layout has been computed. However, you can modify layout in your event handler method, which means that layout will be computed once more before rendering.
The following example shows how you can provide custom drawing in a xref:System.Windows.Media.CompositionTarget event handler method. In this case, the background color of the xref:System.Windows.Controls.Canvas is drawn with a color value based on the coordinate position of the mouse. If you move the mouse inside the xref:System.Windows.Controls.Canvas, its background color changes. In addition, the average frame rate is calculated, based on the current elapsed time and the total number of rendered frames.
[!code-csharpCompositionTargetSample#CompositionTarget2] [!code-vbCompositionTargetSample#CompositionTarget2]
You may discover that your custom drawing runs at different speeds on different computers. This is because your custom drawing is not frame-rate independent. Depending on the system you are running and the workload of that system, the xref:System.Windows.Media.CompositionTarget.Rendering event may be called a different number of times per second. For information on determining the graphics hardware capability and performance for a device that runs a [!INCLUDETLA2#tla_winclient] application, see Graphics Rendering Tiers.
Adding or removing a rendering xref:System.EventHandler delegate while the event is firing will be delayed until after the event is finished firing. This is consistent with how xref:System.MulticastDelegate-based events are handled in the Common Language Runtime (CLR). Also note that rendering events are not guaranteed to be called in any particular order. If you have multiple xref:System.EventHandler delegates that rely on a particular order, you should register a single xref:System.Windows.Media.CompositionTarget.Rendering event and multiplex the delegates in the correct order yourself.