XamlCompositionBrushBase XamlCompositionBrushBase XamlCompositionBrushBase XamlCompositionBrushBase Class


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

public : class XamlCompositionBrushBase : Brush, IXamlCompositionBrushBase, IXamlCompositionBrushBaseOverrides, IXamlCompositionBrushBaseProtected
public class XamlCompositionBrushBase : Brush, IXamlCompositionBrushBase, IXamlCompositionBrushBaseOverrides, IXamlCompositionBrushBaseProtected
Public Class XamlCompositionBrushBase Inherits Brush Implements IXamlCompositionBrushBase, IXamlCompositionBrushBaseOverrides, IXamlCompositionBrushBaseProtected
var xamlCompositionBrushBase = new xamlCompositionBrushBase();
Windows 10 requirements
Device family
Windows 10 Creators Update (introduced v10.0.15063.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v4)


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
// 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:

<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.


XamlCompositionBrushBase() XamlCompositionBrushBase() XamlCompositionBrushBase() XamlCompositionBrushBase()

Provides base class initialization behavior for XamlCompositionBrushBase derived classes.

protected : XamlCompositionBrushBase()
protected XamlCompositionBrushBase()
Protected Sub New()
var xamlCompositionBrushBase = new xamlCompositionBrushBase();


CompositionBrush CompositionBrush CompositionBrush CompositionBrush

Gets or sets the CompositionBrush used by this XAML brush.

protected : CompositionBrush CompositionBrush { get; set; }
protected CompositionBrush CompositionBrush { get; set; }
Protected ReadWrite Property CompositionBrush As CompositionBrush
var compositionBrush = xamlCompositionBrushBase.compositionBrush;
xamlCompositionBrushBase.compositionBrush = compositionBrush;

FallbackColor FallbackColor FallbackColor FallbackColor

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

public : Color FallbackColor { get; set; }
public Color FallbackColor { get; set; }
Public ReadWrite Property FallbackColor As Color
var color = xamlCompositionBrushBase.fallbackColor;
xamlCompositionBrushBase.fallbackColor = color;
Color Color Color Color

The color to use for rendering in place of the composition brush.


Some cases where the CompositionBrush can't be rendered include:

  • in the Visual Studio visual designer
  • when printing
  • in software rendering mode

FallbackColorProperty FallbackColorProperty FallbackColorProperty FallbackColorProperty

Identifies the FallbackColor dependency property.

public : static DependencyProperty FallbackColorProperty { get; }
public static DependencyProperty FallbackColorProperty { get; }
Public Static ReadOnly Property FallbackColorProperty As DependencyProperty
var dependencyProperty = Windows.UI.Xaml.Media.XamlCompositionBrushBase.fallbackColorProperty;
DependencyProperty DependencyProperty DependencyProperty DependencyProperty

The identifier for the FallbackColor dependency property.

Dispatcher Dispatcher Dispatcher Dispatcher

Inherited from DependencyObject

Opacity Opacity Opacity Opacity

Inherited from Brush

OpacityProperty OpacityProperty OpacityProperty OpacityProperty

Inherited from Brush

RelativeTransform RelativeTransform RelativeTransform RelativeTransform

Inherited from Brush

RelativeTransformProperty RelativeTransformProperty RelativeTransformProperty RelativeTransformProperty

Inherited from Brush

Transform Transform Transform Transform

Inherited from Brush

TransformProperty TransformProperty TransformProperty TransformProperty

Inherited from Brush


OnConnected() OnConnected() OnConnected() OnConnected()

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.

protected : virtual void OnConnected()
protected virtual void OnConnected()
Protected Overridable Function OnConnected() As void

OnDisconnected() OnDisconnected() OnDisconnected() OnDisconnected()

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.

protected : virtual void OnDisconnected()
protected virtual void OnDisconnected()
Protected Overridable Function OnDisconnected() As void

ClearValue(DependencyProperty) ClearValue(DependencyProperty) ClearValue(DependencyProperty) ClearValue(DependencyProperty)

Inherited from DependencyObject

GetAnimationBaseValue(DependencyProperty) GetAnimationBaseValue(DependencyProperty) GetAnimationBaseValue(DependencyProperty) GetAnimationBaseValue(DependencyProperty)

Inherited from DependencyObject

GetValue(DependencyProperty) GetValue(DependencyProperty) GetValue(DependencyProperty) GetValue(DependencyProperty)

Inherited from DependencyObject

ReadLocalValue(DependencyProperty) ReadLocalValue(DependencyProperty) ReadLocalValue(DependencyProperty) ReadLocalValue(DependencyProperty)

Inherited from DependencyObject

RegisterPropertyChangedCallback(DependencyProperty,DependencyPropertyChangedCallback) RegisterPropertyChangedCallback(DependencyProperty,DependencyPropertyChangedCallback) RegisterPropertyChangedCallback(DependencyProperty,DependencyPropertyChangedCallback) RegisterPropertyChangedCallback(DependencyProperty,DependencyPropertyChangedCallback)

Inherited from DependencyObject

SetValue(DependencyProperty,Object) SetValue(DependencyProperty,Object) SetValue(DependencyProperty,Object) SetValue(DependencyProperty,Object)

Inherited from DependencyObject

UnregisterPropertyChangedCallback(DependencyProperty,Int64) UnregisterPropertyChangedCallback(DependencyProperty,Int64) UnregisterPropertyChangedCallback(DependencyProperty,Int64) UnregisterPropertyChangedCallback(DependencyProperty,Int64)

Inherited from DependencyObject