Fix #3612 - Default value of ShadowAssist.CacheMode set to 'null' (#3616)

* Fix #3612 - Default value of ShadowAssist.CacheMode set to 'null'

* CacheMode changed to ShadowAssist.CacheMode binding

* Add documentation about CacheMode and ShadowAssist.CacheMode

* Added source articles

* Update docs/rendering-performance.md

* Update docs/rendering-performance.md

* Update docs/rendering-performance.md

* Update docs/rendering-performance.md

* Update docs/rendering-performance.md

---------

Co-authored-by: Kevin B <[email protected]>

Author: MichelMichels

README.md

@@ -32,6 +32,7 @@ Comprehensive and easy to use Material Design theme and control library for the
 - [Building the source](#building-the-source)
 - [Screenshots](#screenshots)
 - [More examples](#more-examples)
+- [FAQ](#faq)
 - [Contributing](#contributing)
 - [Mentions](#mentions)
 - [Backers](#backers)
@@ -134,6 +135,10 @@ This repository also contains 3 different demo applications:
 * [F1ix](http://materialdesigninxaml.net/f1ix)
 * [Motion List](https://github.com/MaterialDesignInXAML/MotionList)
 
+## FAQ
+
+* [How to increase rendering performance?](docs/rendering-performance.md)
+
 ## Contributing
 
 Before contributing code read the [Contribution Guidelines](.github/CONTRIBUTING.md)

docs/rendering-performance.md

@@ -0,0 +1,69 @@
+[Home](..\README.md) > How to increase rendering performance?
+
+---
+
+# How to increase rendering performance?
+
+## Background information
+
+Every class inheriting from [`UIElement`](https://learn.microsoft.com/dotnet/api/system.windows.uielement?view=windowsdesktop-8.0) 
+contains a property [`CacheMode`](https://learn.microsoft.com/dotnet/api/system.windows.uielement.cachemode?view=windowsdesktop-8.0). To quote Microsoft's documentation:
+
+> Set the CacheMode property when you need to increase performance for content that is time consuming to render. For 
+> more information, see [BitmapCache](https://learn.microsoft.com/dotnet/api/system.windows.media.bitmapcache?view=windowsdesktop-8.0).
+
+The default value is `null` as to not use any form of caching. This makes the controls sharp and crisp.
+
+## Setting `UIElement.CacheMode`
+
+An example how to set a `CacheMode`:
+
+```xaml
+<!-- This should decrease rendering time -->
+
+<ToggleButton>
+    <ToggleButton.CacheMode>
+        <BitmapCache 
+            EnableClearType="True"
+            RenderAtScale="1"
+            SnapsToDevicePixels="True" />
+    </ToggleButton.CacheMode>
+</ToggleButton>
+```
+
+Increase the `RenderAtScale` value, will sharpen the control, but it will also make it more pixelized when drawn smaller.
+
+> [!NOTE]
+> The default value of `UIElement.CacheMode` is `null`.
+
+## Advanced: setting `ShadowAssist.CacheMode`
+
+Material Design in XAML toolkit also provides you with an attached property `ShadowAssist.CacheMode`. 
+This attached property is used in places where a simple `CacheMode` property would not suffice. This could be in situations 
+where the property should be inherited, as `UIElement.CacheMode` does not support property inheritance.
+
+This attached property is set through binding on a `CacheMode` property under the parent control.
+
+An example of this property being used:
+```xaml
+<!-- Found inside MaterialDesignTheme.ToggleButton.xaml -->
+
+<AdornerDecorator CacheMode="{Binding RelativeSource={RelativeSource Self}, Path=(wpf:ShadowAssist.CacheMode)}">
+    <Ellipse x:Name="Thumb" ... />
+</AdornerDecorator>
+```
+
+> [!NOTE]
+> The default value of `ShadowAssist.CacheMode` is `null`.
+
+## Example
+
+| With `CacheMode` set                                                                                                              | Without `CacheMode` set                                                                                                           |
+| --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| ![image](https://github.com/MaterialDesignInXAML/MaterialDesignInXamlToolkit/assets/6505319/9401be9c-9939-4c02-b37e-610707ea9e5c) | ![image](https://github.com/MaterialDesignInXAML/MaterialDesignInXamlToolkit/assets/6505319/928e6f70-60a2-4e0a-b8e5-f1955d3cc6f4) |
+
+## Further reading
+
+Some interesting articles with more in-depth information:
+* [Property value inheritance (WPF .NET)](https://learn.microsoft.com/dotnet/desktop/wpf/properties/property-value-inheritance?view=netdesktop-7.0)
+* [UIElement.CacheMode Property](https://learn.microsoft.com/dotnet/api/system.windows.uielement.cachemode?view=windowsdesktop-8.0)

src/MaterialDesignThemes.Wpf/ShadowAssist.cs

@@ -79,7 +79,7 @@ public static bool GetDarken(DependencyObject element)
 
     #region AttachedProperty : CacheModeProperty
     public static readonly DependencyProperty CacheModeProperty = DependencyProperty.RegisterAttached(
-        "CacheMode", typeof(CacheMode), typeof(ShadowAssist), new FrameworkPropertyMetadata(new BitmapCache { EnableClearType = true, SnapsToDevicePixels = true }, FrameworkPropertyMetadataOptions.Inherits));
+        "CacheMode", typeof(CacheMode), typeof(ShadowAssist), new FrameworkPropertyMetadata(null, FrameworkPropertyMetadataOptions.Inherits));
 
     public static void SetCacheMode(DependencyObject element, CacheMode value)
     {

src/MaterialDesignThemes.Wpf/Themes/MaterialDesignTheme.ToolBar.xaml

@@ -186,11 +186,8 @@
                      IsOpen="{Binding IsOverflowOpen, RelativeSource={RelativeSource TemplatedParent}}"
                      Placement="Bottom"
                      PopupAnimation="{DynamicResource {x:Static SystemParameters.ComboBoxPopupAnimationKey}}"
-                     StaysOpen="false">
-                <!-- warning, this will cache the inner item as well, consider separating the shadow from the item if possible -->
-                <Popup.CacheMode>
-                  <BitmapCache EnableClearType="True" SnapsToDevicePixels="True" />
-                </Popup.CacheMode>
+                     StaysOpen="false"
+                     CacheMode="{Binding RelativeSource={RelativeSource Self}, Path=(wpf:ShadowAssist.CacheMode)}">
                 <Border x:Name="ToolBarSubMenuBorder"
                         Margin="1"
                         Background="{DynamicResource MaterialDesign.Brush.ToolBar.Background}"