XamlCompositionBrushBase Class


Provides a base class used to create XAML brushes that paint an area with a CompositionBrush.

Equivalent WinUI class: Microsoft.UI.Xaml.Media.XamlCompositionBrushBase.

public ref class XamlCompositionBrushBase : Brush
/// [Windows.Foundation.Metadata.Composable(Windows.UI.Xaml.Media.IXamlCompositionBrushBaseFactory, Windows.Foundation.Metadata.CompositionType.Protected, 262144, "Windows.Foundation.UniversalApiContract")]
/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 262144)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Static(Windows.UI.Xaml.Media.IXamlCompositionBrushBaseStatics, 262144, "Windows.Foundation.UniversalApiContract")]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
/// [Windows.Foundation.Metadata.WebHostHidden]
class XamlCompositionBrushBase : Brush
[Windows.Foundation.Metadata.Composable(typeof(Windows.UI.Xaml.Media.IXamlCompositionBrushBaseFactory), Windows.Foundation.Metadata.CompositionType.Protected, 262144, "Windows.Foundation.UniversalApiContract")]
[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 262144)]
[Windows.Foundation.Metadata.Static(typeof(Windows.UI.Xaml.Media.IXamlCompositionBrushBaseStatics), 262144, "Windows.Foundation.UniversalApiContract")]
public class XamlCompositionBrushBase : Brush
Public Class XamlCompositionBrushBase
Inherits Brush

Windows 10 requirements

Device family
Windows 10 Creators Update (introduced in 10.0.15063.0)
API contract
Windows.Foundation.UniversalApiContract (introduced in v4.0)


This example shows the definition for a custom brush that draws a blurred copy of whatever is behind a UIElement where the brush is applied using a Win2D blur effect and a CompositionBackdropBrush:

public sealed class BackdropBlurBrush : XamlCompositionBrushBase
    public static readonly DependencyProperty BlurAmountProperty = DependencyProperty.Register(
        new PropertyMetadata(0.0, new PropertyChangedCallback(OnBlurAmountChanged)

    public double BlurAmount
        get { return (double)GetValue(BlurAmountProperty); }
        set { SetValue(BlurAmountProperty, value); }

    private static void OnBlurAmountChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
        var brush = (BackdropBlurBrush)d;
        // Unbox and set a new blur amount if the CompositionBrush exists.
        brush.CompositionBrush?.Properties.InsertScalar("Blur.BlurAmount", (float)(double)e.NewValue);            

    public BackdropBlurBrush()

    protected override void OnConnected()
        // Delay creating composition resources until they're required.
        if (CompositionBrush == null)
            var backdrop = Window.Current.Compositor.CreateBackdropBrush();                

            // Use a Win2D blur affect applied to a CompositionBackdropBrush.
            var graphicsEffect = new GaussianBlurEffect
                Name = "Blur",
                BlurAmount = (float)this.BlurAmount,
                Source = new CompositionEffectSourceParameter("backdrop")

            var effectFactory = Window.Current.Compositor.CreateEffectFactory(graphicsEffect, new[] { "Blur.BlurAmount" });
            var effectBrush = effectFactory.CreateBrush();

            effectBrush.SetSourceParameter("backdrop", backdrop);

            CompositionBrush = effectBrush;

    protected override void OnDisconnected()
        // Dispose of composition resources when no longer in use.
        if (CompositionBrush != null)
            CompositionBrush = null;
Public NotInheritable Class BackdropBlurBrush
    Inherits XamlCompositionBrushBase

    Public Shared ReadOnly BlurAmountProperty As DependencyProperty = DependencyProperty.Register(
            New PropertyMetadata(0.0, New PropertyChangedCallback(AddressOf OnBlurAmountChanged)

    Public Property BlurAmount As Double
            Return DirectCast(GetValue(BlurAmountProperty), Double)
        End Get
            SetValue(BlurAmountProperty, Value)
        End Set
    End Property

    Private Shared Sub OnBlurAmountChanged(d As DependencyObject, e As DependencyPropertyChangedEventArgs)
        Dim brush = DirectCast(d, BackdropBlurBrush)
        ' Unbox And set a New blur amount if the CompositionBrush exists.
        brush.CompositionBrush?.Properties.InsertScalar("Blur.BlurAmount", Convert.ToSingle(DirectCast(e.NewValue, Double)))
    End Sub

    Protected Overrides Sub OnConnected()
        If Me.CompositionBrush Is Nothing Then

            Dim backdrop As CompositionBackdropBrush = Window.Current.Compositor.CreateBackdropBrush()

            ' Use a Win2D blur affect applied to a CompositionBackdropBrush.
            Dim graphicsEffect As GaussianBlurEffect = New GaussianBlurEffect()
            graphicsEffect.Name = "Blur"
            graphicsEffect.BlurAmount = Me.BlurAmount
            graphicsEffect.Source = New CompositionEffectSourceParameter("backdrop")

            Dim effectFactory As CompositionEffectFactory = Window.Current.Compositor.CreateEffectFactory(graphicsEffect, New String() {"Blur.BlurAmount"})
            Dim effectBrush As CompositionEffectBrush = effectFactory.CreateBrush()

            effectBrush.SetSourceParameter("backdrop", backdrop)

            CompositionBrush = effectBrush
        End If
    End Sub

    Protected Overrides Sub OnDisconnected()
        ' Dispose of composition resources when no longer in use.
        If CompositionBrush IsNot Nothing Then
            CompositionBrush = Nothing
        End If
    End Sub
End Class

For the C++/WinRT code example below, you'll need to add a Midl File (.idl) file to your project.

// BackdropBlurBrush.idl
namespace MyApp
    runtimeclass BackdropBlurBrush : Windows.UI.Xaml.Media.XamlCompositionBrushBase
        static Windows.UI.Xaml.DependencyProperty BlurAmountProperty{ get; };
        Double BlurAmount;
// pch.h
// You'll need to install the Microsoft Win2D NuGet package for this code example.
#include <winrt/Microsoft.Graphics.Canvas.Effects.h>
#include <winrt/Windows.Graphics.Effects.h>

// BackdropBlurBrush.h.
struct BackdropBlurBrush : BackdropBlurBrushT<BackdropBlurBrush>
    BackdropBlurBrush() = default;

    static Windows::UI::Xaml::DependencyProperty BlurAmountProperty() { return m_blurAmountProperty; }

    double BlurAmount()
        return winrt::unbox_value<double>(GetValue(m_blurAmountProperty));

    void BlurAmount(double value)
        SetValue(m_blurAmountProperty, winrt::box_value(value));

    void OnConnected();
    void OnDisconnected();

    static void OnBlurAmountChanged(Windows::UI::Xaml::DependencyObject const& d, Windows::UI::Xaml::DependencyPropertyChangedEventArgs const& e);

    static Windows::UI::Xaml::DependencyProperty m_blurAmountProperty;

// WindowBlurBrush.cpp.
Windows::UI::Xaml::DependencyProperty BackdropBlurBrush::m_blurAmountProperty =
        Windows::UI::Xaml::PropertyMetadata{ winrt::box_value(0.), Windows::UI::Xaml::PropertyChangedCallback{ &BackdropBlurBrush::OnBlurAmountChanged } }

void BackdropBlurBrush::OnBlurAmountChanged(Windows::UI::Xaml::DependencyObject const& d, Windows::UI::Xaml::DependencyPropertyChangedEventArgs const& e)
    auto brush{ d.as<MyApp::BackdropBlurBrush>() };
    // Unbox and set a new blur amount if the CompositionBrush exists.
    if (brush.CompositionBrush() != nullptr)
        brush.CompositionBrush().Properties().InsertScalar(L"Blur.BlurAmount", (float)winrt::unbox_value<double>(e.NewValue()));

void BackdropBlurBrush::OnConnected()
    // Delay creating composition resources until they're required.
    if (!CompositionBrush())
        auto backdrop{ Windows::UI::Xaml::Window::Current().Compositor().CreateBackdropBrush() };

        // Use a Win2D blur affect applied to a CompositionBackdropBrush.
        Microsoft::Graphics::Canvas::Effects::GaussianBlurEffect graphicsEffect{};

        auto effectFactory{ Windows::UI::Xaml::Window::Current().Compositor().CreateEffectFactory(graphicsEffect, { L"Blur.BlurAmount" }) };
        auto effectBrush{ effectFactory.CreateBrush() };

        effectBrush.SetSourceParameter(L"backdrop", backdrop);


void BackdropBlurBrush::OnDisconnected()
    // Dispose of composition resources when no longer in use.
    if (CompositionBrush())
// WindowBlurBrush.h:
public ref class BackdropBlurBrush sealed :
    public Windows::UI::Xaml::Media::XamlCompositionBrushBase

    static property Windows::UI::Xaml::DependencyProperty^ BlurAmountProperty
        Windows::UI::Xaml::DependencyProperty^ get() { return m_blurAmountProperty; }

    property double BlurAmount
        double get() 
            return static_cast<double>(GetValue(BlurAmountProperty));
        void set(double value) 
            SetValue(BlurAmountProperty, value);

    virtual void OnConnected() override;
    virtual void OnDisconnected() override;	
    static Windows::UI::Xaml::DependencyProperty^ m_blurAmountProperty;
    static void OnBlurAmountChanged(Windows::UI::Xaml::DependencyObject^ d, Windows::UI::Xaml::DependencyPropertyChangedEventArgs^ e);

// WindowBlurBrush.cpp:
DependencyProperty^ BackdropBlurBrush::m_blurAmountProperty = DependencyProperty::Register(
    ref new PropertyMetadata(0.0, ref new PropertyChangedCallback(OnBlurAmountChanged))


void BackdropBlurBrush::OnBlurAmountChanged(DependencyObject^ d, DependencyPropertyChangedEventArgs^ e)
    auto brush = static_cast<BackdropBlurBrush^>(d);
    // Unbox and set a new blur amount if the CompositionBrush exists
    if (brush->CompositionBrush != nullptr)
        brush->CompositionBrush->Properties->InsertScalar("Blur.BlurAmount", (float)static_cast<double>(e->NewValue));

void BackdropBlurBrush::OnConnected()
    // Delay creating composition resources until they're required
    if (CompositionBrush == nullptr)
        auto backdrop = Window::Current->Compositor->CreateBackdropBrush();

        // Use a Win2D blur affect applied to a CompositionBackdropBrush
        auto graphicsEffect = ref new GaussianBlurEffect();
        graphicsEffect->Name = "Blur";
        graphicsEffect->BlurAmount = static_cast<float>(this->BlurAmount);
        graphicsEffect->Source = ref new CompositionEffectSourceParameter("backdrop");

        auto animatableProperties = ref new Platform::Collections::Vector<Platform::String^>();

        auto effectFactory = Window::Current->Compositor->CreateEffectFactory(graphicsEffect, animatableProperties);
        auto effectBrush = effectFactory->CreateBrush();

        effectBrush->SetSourceParameter("backdrop", backdrop);

        CompositionBrush = effectBrush;

void BackdropBlurBrush::OnDisconnected()
    // Dispose of composition resources when no longer in use
    if (CompositionBrush != nullptr)
        delete CompositionBrush;
        CompositionBrush = nullptr;

The above brush can then be used like any other XAML brush type to paint UIElements, for example:

For C++/WinRT, also add #include "BackdropBlurBrush.h" to MainPage.h.

<Ellipse Width="100" Height="100">
        <local:BackdropBlurBrush BlurAmount="10" />


You can use XamlCompositionBrushBase to create custom brushes.

For example, it can be used to create a brush that applies effects to XAML UIElements using a CompositionEffectBrush, or a SceneLightingEffect that controls the reflective properties of elements when being lit by a XamlLight, or a whole series of effects chained together to produce something more complex.

When creating a brush, it's usually a good practice to delay creating a CompositionBrush and any related resources until the brush is being used. The OnConnected method is called when a brush is first used on screen to paint an element, so you can override OnConnected to safely create resources only when they're needed. This means you can create an instance of a brush in a ResourceDictionary then reference that brush resource later from other parts of UI definitions and only pay the cost of creating composition resources when the brush is actually in use.

It's also a good practice to dispose of composition resources when they're no longer in use. The OnDisconnected method is called when a brush instance is no longer in use anywhere on the screen, so you can override OnDisconnected to safely dispose of resources. If the brush is later used again after being disconnected then OnConnected will be called again.



Provides base class initialization behavior for XamlCompositionBrushBase derived classes.

Equivalent WinUI constructor: Microsoft.UI.Xaml.Media.XamlCompositionBrushBase.XamlCompositionBrushBase.



Gets or sets the CompositionBrush used by this XAML brush.

Equivalent WinUI property: Microsoft.UI.Xaml.Media.XamlCompositionBrushBase.CompositionBrush.


Gets the CoreDispatcher that this object is associated with. The CoreDispatcher represents a facility that can access the DependencyObject on the UI thread even if the code is initiated by a non-UI thread.

Equivalent WinUI property: Microsoft.UI.Xaml.DependencyObject.Dispatcher.

(Inherited from DependencyObject)

The color to use for rendering in case the CompositionBrush can't be rendered.

Equivalent WinUI property: Microsoft.UI.Xaml.Media.XamlCompositionBrushBase.FallbackColor.


Identifies the FallbackColor dependency property.

Equivalent WinUI property: Microsoft.UI.Xaml.Media.XamlCompositionBrushBase.FallbackColorProperty.


Gets or sets the degree of opacity of a Brush.

Equivalent WinUI property: Microsoft.UI.Xaml.Media.Brush.Opacity.

(Inherited from Brush)

Gets or sets the transformation that is applied to the brush using relative coordinates.

Equivalent WinUI property: Microsoft.UI.Xaml.Media.Brush.RelativeTransform.

(Inherited from Brush)

Gets or sets the transformation that is applied to the brush.

Equivalent WinUI property: Microsoft.UI.Xaml.Media.Brush.Transform.

(Inherited from Brush)



Clears the local value of a dependency property.

Equivalent WinUI method: Microsoft.UI.Xaml.DependencyObject.ClearValue.

(Inherited from DependencyObject)

Returns any base value established for a dependency property, which would apply in cases where an animation is not active.

Equivalent WinUI method: Microsoft.UI.Xaml.DependencyObject.GetAnimationBaseValue.

(Inherited from DependencyObject)

Returns the current effective value of a dependency property from a DependencyObject.

Equivalent WinUI method: Microsoft.UI.Xaml.DependencyObject.GetValue.

(Inherited from DependencyObject)

Invoked when a brush is first used on screen to paint an element.

When implemented in a derived class, you can create a CompositionBrush instance and provide it to the framework by setting the CompositionBrush property.

OnDisconnected will be called when the brush is no longer being used to paint any elements.

Equivalent WinUI method: Microsoft.UI.Xaml.Media.XamlCompositionBrushBase.OnConnected.


Invoked when the brush is no longer being used to paint any elements.

When implemented in a derived class, you can safely dispose of the compostion brush and other composition resources.

OnConnected will be called again if the brush is later used to paint any elements after being disconnected.

Equivalent WinUI method: Microsoft.UI.Xaml.Media.XamlCompositionBrushBase.OnDisconnected.

PopulatePropertyInfo(String, AnimationPropertyInfo)

Defines a property that can be animated.

Equivalent WinUI method: Microsoft.UI.Xaml.Media.Brush.PopulatePropertyInfo.

(Inherited from Brush)
PopulatePropertyInfoOverride(String, AnimationPropertyInfo)

When overridden in a derived class, defines a property that can be animated.

Equivalent WinUI method: Microsoft.UI.Xaml.Media.Brush.PopulatePropertyInfoOverride.

(Inherited from Brush)

Returns the local value of a dependency property, if a local value is set.

Equivalent WinUI method: Microsoft.UI.Xaml.DependencyObject.ReadLocalValue.

(Inherited from DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)

Registers a notification function for listening to changes to a specific DependencyProperty on this DependencyObject instance.

Equivalent WinUI method: Microsoft.UI.Xaml.DependencyObject.RegisterPropertyChangedCallback.

(Inherited from DependencyObject)
SetValue(DependencyProperty, Object)

Sets the local value of a dependency property on a DependencyObject.

Equivalent WinUI method: Microsoft.UI.Xaml.DependencyObject.SetValue.

(Inherited from DependencyObject)
UnregisterPropertyChangedCallback(DependencyProperty, Int64)

Cancels a change notification that was previously registered by calling RegisterPropertyChangedCallback.

Equivalent WinUI method: Microsoft.UI.Xaml.DependencyObject.UnregisterPropertyChangedCallback.

(Inherited from DependencyObject)

Applies to