UIElement.CacheMode Property

Definition

Namespace:

Microsoft.UI.Xaml

Gets or sets a value that indicates that rendered content should be cached as a composited bitmap when possible.

public:
 property CacheMode ^ CacheMode { CacheMode ^ get(); void set(CacheMode ^ value); };

CacheMode CacheMode();

void CacheMode(CacheMode value);

public CacheMode CacheMode { get; set; }

var cacheMode = uIElement.cacheMode;
uIElement.cacheMode = cacheMode;

Public Property CacheMode As CacheMode

<uiElement CacheMode="BitmapCache" />

Property Value

CacheMode

A value that indicates that rendered content should be cached as a composited bitmap when possible. If you specify a value of CacheMode, rendering operations from RenderTransform and Opacity execute on the graphics processing unit (GPU), if available. The default is null, which does not enable a cached composition mode.

Remarks

Set this value to enable the caching behavior that offloads RenderTransform and Opacity bitmaps to the graphics processing unit (GPU). Otherwise, leave it as null.

For XAML, the string literal "BitmapCache" is the only enabled value you can use to set CacheMode as an attribute.

Note

BitmapCache is the only existing practical derived classes in the Windows Runtime API that enables this behavior (the CacheMode type is an intermediate type that exists only for infrastructure and legacy reasons).

If setting CacheMode in code, set it to a new value of BitmapCache, like this:

<Canvas x:Name="canvas1"/>

canvas1.CacheMode = new BitmapCache();

#include <winrt/Windows.UI.Xaml.Media.h>
...
canvas1().CacheMode(Windows::UI::Xaml::Media::BitmapCache{});

Do not generally apply CacheMode values to elements without testing and profiling first. Caching to the graphics processing unit (GPU) is intended only for a minority of possible rendering situations for an app, and it's expected that you will profile various combinations of when and where in your UI to apply a CacheMode setting. Overuse of CacheMode can hurt performance rather than help it. It’s best to profile the app surface area to determine which targeted areas are most expensive to render, and to experiment with caching only certain elements based on those results. For more info on how to profile for rendering, see the "Cache static content" section of the Optimize your XAML markup topic.

Avoid using CacheMode and storyboarded animations together. Caching content where Opacity or RenderTransform are animated causes the animations to become dependent animations, even if the animation is zero-duration. To even see those animations run you'd have to set EnableDependentAnimation to true, and a dependent animation usually invalidates all the performance gains you might get from caching the composition. Opacity often is animated by visual states in control templates, so this is a consideration even if you aren't declaring any of your own storyboarded animations in XAML pages.

See also

• Optimize your XAML markup
• Storyboarded animations